> ## 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.
# For Your Coding Agent
> The build reference for coding agents integrating Tako Search. Self-contained and copy-paste-ready — endpoint, X-API-Key auth, every request parameter, the response shape, and runnable cURL, Python, and TypeScript examples. Use this page to generate a working Search integration.
This page is a complete, self-contained reference for building against **Tako Search**. It is written for coding agents (and developers in a hurry): every example runs after you supply an API key, every parameter is grounded in the live API, and the common mistakes are called out explicitly. For the auto-generated schema, see the [Search API reference](/api-reference/search-v3); for a narrative introduction, see the [Overview](/documentation/integrating-tako/search/overview).
## What Search does
`POST https://tako.com/api/v3/search` takes a natural-language `query` and returns **both data results — Tako knowledge cards** (interactive, embeddable data visualizations with structured fields, named sources, and methodology) — **and web search results**, with no synthesized answer on top. Reach for it when you want to render or post-process the results yourself. Responses are compact and fast, so you can call it frequently and in parallel inside agentic loops.
Unlike a web-search API that returns text snippets, each Tako card is a live visualization backed by structured data and attribution — so you get renderable, citable results, not just links.
* **Base URL:** `https://tako.com/api/`
* **Auth:** send your API key in the **`X-API-Key`** request header (not a bearer token). Create a key in the [Tako console](https://tako.com/console/api-keys).
* **Request body** is shared with [Answer](/documentation/integrating-tako/answer/overview) — the only difference is Answer adds a synthesized `answer` string.
## Install
```bash theme={null}
pip install tako-sdk # Python
npm install tako-sdk # TypeScript / JavaScript
```
## Minimal working example
Each snippet makes the same call and is complete after you set `TAKO_API_KEY`.
```bash cURL theme={null}
curl -X POST https://tako.com/api/v3/search \
-H "X-API-Key: $TAKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What is the price of Silver?"
}'
```
```python 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)
```
```typescript TypeScript theme={null}
import { Tako } from "tako-sdk";
const tako = new Tako({ apiKey: process.env.TAKO_API_KEY! });
const results = await tako.search({ query: "What is the price of Silver?" });
console.log(results.request_id);
for (const card of results.cards ?? []) {
console.log(card.title, card.webpage_url);
}
```
## Request parameters
The body is a `SearchRequest`. Only `query` is required.
| Parameter | Type | Default | Description |
| ----------------- | -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | — *(required)* | The natural-language query. Inject session context for relevance (e.g. `"MSFT stock price last 6 months"` rather than `"MSFT"`). |
| `effort` | string enum | `fast` | `fast` (balanced default), `instant` (serves cached embeds without re-running data retrieval — fastest, available on all tiers), or `deep` (widens retrieval and adds an LLM rerank — premium tier). |
| `sources` | object | both sources, 5 results each | Which indexes to search. See [Choosing sources](#choosing-sources). |
| `country_code` | string | `US` | ISO 3166-1 alpha-2 country code. |
| `locale` | string | `en-US` | BCP-47 locale. |
| `timezone` | string \| null | none | IANA timezone (e.g. `America/New_York`). |
| `output_settings` | object \| null | none | Response-shape control: `image_dark_mode` (bool) and `force_refresh` (bool, default `false`, **`instant` mode only**). |
`instant` effort cannot be combined with `sources.data.defer_data_retrieval` — `instant` serves cached embeds and skips the retrieval that `defer_data_retrieval` defers.
### Latency
Target p50 latency (not a guarantee), by `effort`:
| `effort` | Target p50 |
| ------------------ | ---------- |
| `instant` | \~300 ms |
| `fast` *(default)* | \~500 ms |
| `deep` | \~5 s |
## Choosing sources
By default Search queries **both** Tako's curated knowledge graph (`data`) and the live web (`web`), 5 results each. `sources` is an **object** whose keys select the indexes — **a source is searched only if its key is present.**
| `sources` value | Searches |
| --------------------------- | ------------------------------------------------ |
| *(omitted)* | both — equivalent to `{ "data": {}, "web": {} }` |
| `{ "data": {} }` | Tako curated knowledge cards only |
| `{ "web": {} }` | web results only |
| `{ "data": {}, "web": {} }` | both, explicitly |
Each source takes optional per-source settings:
| Setting | Applies to | Type | Default | Description |
| ---------------------- | ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `count` | `data`, `web` | integer (1–20) | `5` | Max results from this source. |
| `include_contents` | `data`, `web` | boolean | `false` | Inline the underlying data in the response. |
| `defer_data_retrieval` | `data` only | boolean | `false` | Return cards faster with a `semantic_description` and a less-detailed `description`. **Mutually exclusive with `include_contents`.** |
```json theme={null}
{
"query": "Nvidia quarterly revenue",
"sources": { "data": { "count": 10 } }
}
```
The legacy key `tako` is accepted as a synonym for `data` and is mapped to it. Prefer `data` in new code.
## What a response looks like
A `200` returns a `SearchResponse`:
```json theme={null}
{
"cards": [
{
"card_id": "KfYeym50vtsF93LMsIFW",
"title": "Silver Spot Price (USD/oz)",
"description": "Spot price of silver in US dollars per troy ounce, updated intraday.",
"webpage_url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
"image_url": "https://tako.com/api/v1/image/KfYeym50vtsF93LMsIFW/",
"embed_url": "https://tako.com/embed/KfYeym50vtsF93LMsIFW/",
"sources": [
{
"source_name": "LBMA",
"source_description": "London Bullion Market Association precious-metals benchmark prices.",
"source_index": "tako"
}
],
"source_indexes": ["tako"],
"content": { "format": "csv", "cost": 0.0 }
}
],
"web_results": [],
"contents_total_cost": 0.0,
"request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
}
```
| Field | Type | Description |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cards` | array | Tako knowledge cards (see below). |
| `web_results` | array | Web results: `title`, `url` (both always present), plus optional `snippet`, `source_name`, `publish_date`, `content`. |
| `contents_total_cost` | number | USD cost of any inlined contents (default `0.0`) — see [Credits & billing](/documentation/additional-resources/credits-and-billing#the-cost-field). |
| `request_id` | string | Always present — log it for support/debugging. |
Each card (`TakoCard`) carries:
| Field | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `card_id` | Stable card identifier. |
| `title`, `description` | Human-readable label and summary. `semantic_description` is also present when `defer_data_retrieval` is used. |
| `embed_url` | iframe URL for the interactive card — see [Embedding Knowledge Cards](/documentation/integrating-tako/embedding-knowledge-cards). |
| `image_url` | Static image of the card. |
| `webpage_url` | Canonical card page; also the `url` you pass to [Contents](#downloading-the-underlying-data). |
| `sources` | Named sources backing the card (`source_name`, `source_description`, `source_index`) — use for attribution. |
| `methodologies` | How the data was collected/derived. |
| `content` | A download descriptor (`format`: `csv` or `text`, `cost`) present when the underlying data is downloadable. |
## When to use Search
Search is for **fast, structured data retrieval** — cards and web results you render or post-process yourself, with no synthesized answer. Reach for it when:
* **You want structured results, not prose.** No answer-synthesis LLM call in the path, so responses come back fast — about **500 ms** on the default `fast` effort (see [Latency](#latency)) — call it frequently and fan out across many entities in parallel.
* **You're feeding an agentic loop that needs a lot of accurate data, fast.** One query per entity; act on the structured cards instead of waiting on generated text.
* **You want more than a single value.** Each result is a knowledge card — a full series with named sources and methodology — so one call returns the surrounding context too, ready to render or compute on.
* **You want broad coverage.** Search queries Tako's curated knowledge graph **and** the live web by default, so you get a meaningful result across far more queries than either source alone.
**Want prose instead?** Use [Answer](/documentation/integrating-tako/answer/for-coding-agent) for a synthesized, source-attributed answer over the same data in one call. **Need multi-step reasoning** — resolving a cohort, ranking a set, multi-hop aggregation? Use the [Agent](/documentation/integrating-tako/agent/for-coding-agent).
## Downloading the underlying data
A result whose data is downloadable includes a `content` descriptor. Pass that result's `webpage_url` (for a card) or `url` (for a web result) to **Contents** (`POST /v1/contents`) to download it — a CSV of a Tako card's data, or extracted text for a web page.
See the [Contents For Your Coding Agent](/documentation/integrating-tako/contents/for-coding-agent) page for the full request and response reference, including `url` vs `inline` delivery modes. To skip the second call, inline the data in this response with the per-source [`include_contents`](#choosing-sources) setting.
## Common mistakes
Avoid these — they are the patterns coding agents most often get wrong.
| Wrong | Correct |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `Authorization: Bearer $KEY` | `X-API-Key: $KEY` |
| `"sources": ["data"]` (array) | `"sources": { "data": {} }` (object — key presence selects the source) |
| Omitting `sources` to get only Tako data | Omitting `sources` searches **both**; pass `{ "data": {} }` for data-only |
| Setting both `defer_data_retrieval` and `include_contents` | Pick one — they are mutually exclusive |
| Combining `effort: "instant"` with `defer_data_retrieval` | Not allowed — use `fast` if you need `defer_data_retrieval` |
| Confusing this with the Agent's `source_indexes` | Search/Answer use the `sources` **object**; the Agent uses a `source_indexes` **array** |
## Errors
Failures return a `BaseAPIError` body: `{ "error_message": "...", "error_type": "..." }`.
| Status | Meaning | Fix |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `400` | Malformed request (bad JSON, invalid parameter). | Validate the body against the parameter table above. |
| `401` | Missing or invalid API key. | Send a valid key in the `X-API-Key` header. |
| `402` | Out of credits (insufficient balance). | Top up credits — see [Credits & billing](/documentation/additional-resources/credits-and-billing#running-out-402). |
| `408` | The request timed out. | Retry; consider `effort: "instant"` for the fastest path. |