For Your Coding Agent

This page is a complete, self-contained reference for building against Tako Answer. 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 Answer API reference; for a narrative introduction, see the Overview.

What Answer does

POST https://tako.com/api/v1/answer takes a natural-language query and returns a synthesized written answer in a single fast call, grounded in real-time, trusted data — alongside the Tako knowledge cards and web results that back it. Use it to ground your own model output and keep what you show consistent with Tako’s data (for example, grounding a stock-price analysis with Tako’s up-to-date pricing card). Answer takes the same request body as Search; the only response difference is the added answer string. Because each backing card ships with named sources and methodology, you get an answer you can attribute and cite, not just a paragraph of text.

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.

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/v1/answer \
  -H "X-API-Key: $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the weather in San Francisco?"
  }'

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)

response = client.answer(SearchRequest(query="What is the weather in San Francisco?"))
print(response.answer)
for card in response.cards or []:
    print(card.title, card.webpage_url)

import { Tako } from "tako-sdk";

const tako = new Tako({ apiKey: process.env.TAKO_API_KEY! });

const response = await tako.answer({ query: "What is the weather in San Francisco?" });
console.log(response.answer);
for (const card of response.cards ?? []) {
  console.log(card.title, card.webpage_url);
}

Request parameters

The body is a SearchRequest — identical to Search. Only query is required; effort (fast default / instant / deep), sources, country_code (US), locale (en-US), timezone, and output_settings all behave exactly as documented in the Search reference.

Forcing entity boundaries in `query`

Tako identifies the entities in the query before it retrieves the cards and web results that ground the answer. 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. Search accepts the same syntax.

Latency

Target p50 latency (not a guarantee), by effort:

`effort`	Target p50
`instant`	~750 ms
`fast` (default)	~950 ms
`deep`	~6 s

Choosing sources

Use both sources. Omit sources and Answer grounds in both Tako’s curated knowledge graph and the live web — the recommended default for the most complete, accurate answer. Narrow to one index only when you have a specific reason.

By default Answer grounds in 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 used only if its key is present:

`sources` value	Grounds in
(omitted)	both — equivalent to `{ "data": {}, "web": {} }`
`{ "data": {} }`	Tako curated knowledge graph only
`{ "web": {} }`	the live web only

Per-source count (1–20, default 5), include_contents, and defer_data_retrieval (data only; mutually exclusive with include_contents) work as in Search. The legacy key tako maps to data.

What a response looks like

A 200 returns an AnswerResponse — a SearchResponse plus a required answer string. cards[0] is the lead card: the best one to show alongside the answer.

{
  "answer": "It's currently 52°F in San Francisco and feels like 52°F, with partly cloudy skies. Today's high is 54°F and the low is 50°F; the rest of the week is expected to be mostly clear with highs around 53–55°F.",
  "cards": [
    {
      "card_id": "mA-C6b48zxyU3G33JJdO",
      "title": "San Francisco, CA Weather Metrics",
      "description": "This card displays the weather forecast for San Francisco, CA for today. Currently, it's 52°F and feels like 52°F. The high for today is 54°F and the low is 50°F.",
      "webpage_url": "https://tako.com/card/mA-C6b48zxyU3G33JJdO/",
      "image_url": "https://tako.com/api/v1/image/mA-C6b48zxyU3G33JJdO/",
      "embed_url": "https://tako.com/embed/mA-C6b48zxyU3G33JJdO/",
      "sources": [
        {
          "source_name": "NOAA National Weather Service",
          "source_description": "The U.S. agency providing weather forecasts and warnings, part of NOAA.",
          "source_index": "tako"
        }
      ],
      "methodologies": [
        {
          "methodology_name": "Data Collection",
          "methodology_description": "Raw meteorological data from NOAA's NWS, sourced from weather.gov, with no statistical adjustments applied."
        }
      ],
      "source_indexes": ["tako"]
    }
  ],
  "web_results": [],
  "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
}

Field	Type	Description
`answer`	string	The synthesized, grounded answer. Always present.
`cards`	array	Backing Tako cards; `cards[0]` is the lead card to display.
`web_results`	array	Backing web results (`title`, `url`, plus optional `snippet`, `source_name`, `publish_date`).
`request_id`	string	Always present — log it for support/debugging.

Backing cards carry the same content/cost fields as Search; credits apply per call — see Credits & billing.

Grounding and attribution

To keep your content accurate and citable, read these fields off each card:

description — a natural-language description of the data and the latest data point.
sources — named sources (source_name, source_description) backing the card.
methodologies — how the data was collected or derived.
image_url — a static image of the card to display next to the answer.

When to use Answer

Answer is for a ready-to-show, source-attributed answer in one call — synthesized prose that draws the best answer from both Tako’s curated data and the live web, shipped with the cards and web results that back it. Reach for it when:

You want prose you can drop straight in. One synchronous call returns a written answer, not raw results to assemble yourself — ideal for chat assistants and any surface that needs text.
The answer has to be citable. Every answer comes back with its backing cards — named sources and methodology — so you can attribute each claim and keep content auditable.
You want it to stay current. Re-run the same query to refresh prose that stays grounded in live data, across Tako’s curated knowledge graph and the live web by default.
You’re grounding your own model. Inline the underlying data with include_contents so your model reasons over real numbers, not snippets.

Only need the raw cards and web results? Use Search — the same request body, without the synthesized answer. Need multi-step reasoning — resolving a cohort, ranking a set, multi-hop aggregation? Use the Agent.

Common mistakes

Avoid these — they are the patterns coding agents most often get wrong.

Wrong	Correct
`Authorization: Bearer $KEY`	`X-API-Key: $KEY`
Posting to `/v1/search` or `/v3/answer`	Answer is `POST /v1/answer`; Search is `POST /v3/search`
`"sources": ["data"]` (array)	`"sources": { "data": {} }` (object — key presence selects the source)
Treating any card as the lead	`cards[0]` is the lead card — display it alongside the `answer`
Showing the `answer` without attribution	Read `sources` / `methodologies` off the backing cards to cite it
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 parameters 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 the request.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

For Your Coding Agent

What Answer does

Install

Minimal working example

Request parameters

Forcing entity boundaries in `query`

Latency

Choosing sources

What a response looks like

Grounding and attribution

When to use Answer

Common mistakes

Errors

​What Answer does

​Install

​Minimal working example

​Request parameters

​Forcing entity boundaries in query

​Latency

​Choosing sources

​What a response looks like

​Grounding and attribution

​When to use Answer

​Common mistakes

​Errors

What Answer does

Install

Minimal working example

Request parameters

Forcing entity boundaries in `query`

Latency

Choosing sources

What a response looks like

Grounding and attribution

When to use Answer

Common mistakes

Errors