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