For Your Coding Agent

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.

Forcing entity boundaries in `query`

Tako identifies the entities in the query before it searches. Double quotes force a phrase to be exactly one entity, and an optional :LABEL suffix sets its type. Use this when you already know the entity — an agent usually does.

{ "query": "\"tesla motors\" club revenue" }
{ "query": "\"Tesla\":PRODUCT price" }

Labels: PERSON, ORG, GPE, LOC, PRODUCT, DATE, EVENT, MONEY, CARDINAL, METRIC, TIME_PERIOD, UNITS. Quoting is all-or-nothing: every " in the query must belong to a non-empty pair of 80 characters or less. If one quote is unmatched, Tako ignores every quote in that query and searches as usual, so an ordinary web-style phrase query still works. An unrecognized label stays in the query text. The quotes never reach the search text. Answer accepts the same syntax.

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`.
`node_ids`	`data` only	array of strings (max 20 distinct)	none	Pin resolved Data Graph node ids: pinned nodes get guaranteed retrieval candidacy + a strong boost; organic results are unaffected. Malformed id → 400; an id that no longer resolves is skipped.
`strict`	`data` only	boolean	`false`	Return only cards matching a pinned node. Requires non-empty `node_ids` (else 400).

{
  "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.

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.
`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 only when the result’s data can be downloaded. If it’s absent, that result’s data isn’t exportable — skip it rather than calling Contents, which will refuse it.

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. Not every result carries one: when a result’s underlying data can’t be exported, content is omitted. Treat its absence as “no download available” and skip the Contents call for that result. 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
Leaving one unmatched `"` in `query`	Pair every quote — a single stray quote turns off entity forcing for the whole query

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.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

For Your Coding Agent

What Search does

Install

Minimal working example

Request parameters

Forcing entity boundaries in `query`

Latency

Choosing sources

What a response looks like

When to use Search

Downloading the underlying data

Common mistakes

Errors

​What Search does

​Install

​Minimal working example

​Request parameters

​Forcing entity boundaries in query

​Latency

​Choosing sources

​What a response looks like

​When to use Search

​Downloading the underlying data

​Common mistakes

​Errors

What Search does

Install

Minimal working example

Request parameters

Forcing entity boundaries in `query`

Latency

Choosing sources

What a response looks like

When to use Search

Downloading the underlying data

Common mistakes

Errors