> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

export const CodingAgentCTA = ({description, href}) => <p className="mt-2 text-lg prose prose-gray dark:prose-invert [&>*]:[overflow-wrap:anywhere]">
    {description} Building with a coding agent?{" "}
    <a href={href}>Give your agent the full reference →</a>
  </p>;

export const PlaygroundButton = ({href = "https://tako.com/playground", label = "Try in Playground"}) => <div className="float-right not-prose ml-4 -mt-12">
    <a href={href} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1.5 rounded-full border border-gray-200 dark:border-white/15 bg-white dark:bg-white/5 px-3 py-1.5 text-sm font-medium text-gray-700 dark:text-gray-200 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:hover:bg-white/10">
      <svg viewBox="0 0 24 24" aria-hidden="true" className="h-3.5 w-3.5 fill-current">
        <path d="M8 5v14l11-7z" />
      </svg>
      {label}
    </a>
  </div>;

<CodingAgentCTA description="Fast data retrieval from proprietary licensed partners and web search results for any written query." href="/documentation/integrating-tako/search/for-coding-agent" />

## When to use Search

[Search](/api-reference/search-v3) is for **fast retrieval you render or post-process yourself**, with no written answer on top. One call returns **both** kinds of result — **data results** (interactive Tako knowledge cards backed by structured data) **and web search results**. Reach for it when:

<CardGroup cols={2}>
  <Card title="You want raw, structured results, not prose" icon="bolt">
    There's no answer-synthesis LLM call in the loop, so results come back fast — quick enough to fan out across many entities in parallel.
  </Card>

  <Card title="You're building an agentic system that needs a lot of accurate data, fast" icon="layer-group">
    Call Search repeatedly — one query per entity — and act on structured results instead of waiting on generated text.
  </Card>

  <Card title="You want more than a single number" icon="chart-column">
    Each result is a knowledge card — a full data series with its sources and methodology, not a lone value — so one query returns the surrounding context too, ready to render or compute on.
  </Card>

  <Card title="You want broad coverage you can trust" icon="globe">
    No single source has everything, so Search queries Tako's curated index (finance, macro, geopolitics, sports, weather) **and** the live web **by default** — broad coverage you can trust.
  </Card>
</CardGroup>

Choosing between Tako's surfaces (see the [full comparison](/documentation/integrating-tako/agent/overview#choosing-a-tako-surface)):

| Surface | What it's for |
| - | - |
| **[Search](/api-reference/search-v3)** | Fast, parallel retrieval of structured data and cards, in one call, no synthesized answer. |
| **[Answer](/documentation/integrating-tako/answer/overview)** | A written, source-attributed answer over the same retrieval, in one call. |
| **[Retrieval Agent](/documentation/integrating-tako/agent/retrieval)** | Multi-step research returning schema-defined structured data and cards. |
| **[Answer Agent](/documentation/integrating-tako/agent/answer)** | Deep research synthesizing a cited answer backed by visualizations. |

## Example

<PlaygroundButton />

Inject context from the user's session into the query to sharpen relevance — send `"MSFT stock price last 6 months"` rather than just `"MSFT"`.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://tako.com/api/v3/search \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "What is the price of Silver?"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install tako-sdk
    ```

    ```python theme={null}
    import os
    from tako import Configuration, SearchRequest
    from tako.lib import Tako

    config = Configuration()
    config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
    client = Tako(config)

    results = client.search(SearchRequest(query="What is the price of Silver?"))
    print(results.request_id)
    for card in results.cards or []:
        print(card.title, card.webpage_url)
    ```
  </Tab>
</Tabs>

<Accordion title="Example Result" defaultOpen={true}>
  <p>
    Query: "What is the price of Silver?"
  </p>

  <iframe width="100%" style={{backgroundColor: '#ffffff'}} src="https://tako.com/embed/KfYeym50vtsF93LMsIFW/?dark_mode=false" scrolling="no" frameborder="0" className="dark:hidden" />

  <iframe width="100%" style={{backgroundColor: '#1A1D1F'}} src="https://tako.com/embed/KfYeym50vtsF93LMsIFW/?dark_mode=true" scrolling="no" frameborder="0" className="hidden dark:block" />
</Accordion>

## Use cases

<AccordionGroup>
  <Accordion title="Pulling real-time data across many entities">
    Fan out Search calls in an agentic loop to gather fresh, structured data fast.

    ```python theme={null}
    for ticker in ["NVDA", "AMD", "INTC"]:
        results = client.search(SearchRequest(query=f"{ticker} quarterly revenue"))
    ```
  </Accordion>

  <Accordion title="Curated data only — skip the web">
    Restrict to Tako's authoritative knowledge graph when you only want vetted sources.

    ```python theme={null}
    results = client.search(SearchRequest(query="US inflation rate", sources={"data": {}}))
    ```
  </Accordion>

  <Accordion title="Rendering interactive cards in your app">
    Embed the live visualization from each result straight into your UI. Each card also carries `title`, `description`, `image_url`, `webpage_url`, and `sources` — use them for labels, a static image, or data provenance alongside the interactive `embed_url`.

    ```python theme={null}
    results = client.search(SearchRequest(query="S&P 500 over the last 5 years"))
    for card in results.cards or []:
        print(card.embed_url)  # drop into an <iframe>
    ```
  </Accordion>

  <Accordion title="Grounding your own model (RAG)">
    Inline the underlying data so your model reasons over numbers, not snippets.

    ```python theme={null}
    results = client.search(SearchRequest(
        query="Palantir federal contract obligations",
        sources={"data": {"include_contents": True}},
    ))
    ```
  </Accordion>
</AccordionGroup>

## Force a phrase to be one entity

Tako identifies the entities in your query before it searches. Put double quotes around a phrase to make Tako treat that phrase as exactly one entity. Use this when you already know the entity and the automatic split gets it wrong — for example, `"tesla motors" club revenue` keeps `tesla motors` together instead of reading `tesla motors club` as one name.

Add `:LABEL` after the closing quote to also set the entity type:

```json theme={null}
{ "query": "\"Tesla\":PRODUCT price" }
```

The available labels are `PERSON`, `ORG`, `GPE`, `LOC`, `PRODUCT`, `DATE`, `EVENT`, `MONEY`, `CARDINAL`, `METRIC`, `TIME_PERIOD`, and `UNITS`.

Three rules apply:

* **Quotes must pair.** If one quote in the query has no partner, or a pair is empty, Tako ignores every quote in that query and searches as usual. This keeps quoted web-search phrases safe.
* **A quoted phrase must be 80 characters or less.** A longer phrase turns off quoting for the whole query.
* **An unknown label stays in the text.** Tako still forces the phrase, but `:LABEL` becomes part of the query, so use only the labels above.

Tako removes the quotes before it searches. [Answer](/documentation/integrating-tako/answer/overview) accepts the same syntax.

## Choosing sources

By default Search queries **both** Tako's curated knowledge graph and the live web. Pass `sources` to control this — an object whose keys are the sources to search. **A source is searched only if its key is present.** Omit `sources` to use the default (both sources, 5 results each):

| `sources` value | Searches |
| - | - |
| omit *(equivalent to `{ "data": {}, "web": {} }`)* | Both (default). |
| `{ "data": {} }` | Tako knowledge cards from the curated knowledge graph only. |
| `{ "web": {} }` | Web results only. |

The legacy value `tako` is accepted as a synonym for `data`.

Each source takes optional per-source settings: `count` (1–20, default 5) and `include_contents` (inline the underlying data in the response). The curated-data source also supports `node_ids`/`strict` for pinning resolved [Data Graph](/documentation/integrating-tako/data-graph/overview) nodes into retrieval. For example, `{ "data": { "count": 10 } }` returns up to 10 Tako cards.

## Grab the data behind a result

Search hands back each card with its metadata; when you want the **numbers themselves**, [Contents](/documentation/integrating-tako/contents/overview) fetches the full data behind a result — a **CSV export** of a Tako card's underlying series, or the **extracted text** of a web page.

A result is downloadable **only when** it carries a `content` descriptor in the response. Pass that result's URL — a card's `webpage_url` or a web result's `url` — to Contents to pull the CSV. If a result has no `content` descriptor, its data can't be exported; that's expected, so skip the Contents call for it.

See the [Contents overview](/documentation/integrating-tako/contents/overview) to get started.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.