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; for a narrative introduction, see the 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.
- Request body is shared with Answer — the only difference is Answer adds a synthesized
answer string.
Install
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.
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?"
}'
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)
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. |
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 |
| 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. |
{
"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:
{
"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. |
request_id | string | Always present — log it for support/debugging. |
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. |
image_url | Static image of the card. |
webpage_url | Canonical card page; also the url you pass to Contents. |
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) — 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 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.
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 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 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. |
408 | The request timed out. | Retry; consider effort: "instant" for the fastest path. |
