Skip to main content
POST
/
v3
/
search
Search
curl --request POST \
  --url https://tako.com/api/v3/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "effort": "fast",
  "sources": {
    "data": {
      "count": 5,
      "include_contents": false,
      "defer_data_retrieval": false
    },
    "web": {
      "count": 5,
      "include_contents": false
    }
  },
  "country_code": "US",
  "locale": "en-US",
  "timezone": "<string>",
  "output_settings": {
    "image_dark_mode": true,
    "force_refresh": false
  }
}
'
{
  "request_id": "<string>",
  "cards": [
    {
      "card_id": "<string>",
      "title": "<string>",
      "description": "<string>",
      "semantic_description": "<string>",
      "webpage_url": "<string>",
      "image_url": "<string>",
      "embed_url": "<string>",
      "sources": [
        {
          "source_name": "S&P Global",
          "source_description": "S&P Global is a US-based financial data and analytics company that provides products and services to the financial industry.",
          "source_index": "tako",
          "url": "https://xignite.com",
          "source_text": "Domestic (28.1%) $154,061,981 | International (71.9%) $394,144,531 | Worldwide $548,206,512. Release Date Nov 7, 2025. Distributor 20th Century Studios."
        }
      ],
      "methodologies": [
        {
          "methodology_name": "Where the Data Comes From - S&P Global",
          "methodology_description": "The financial metrics are collected from S&P Global, where information is sourced from original regulatory filings, press releases, and subsequent restatements. Data points, including over 5,000 financial, supplemental, segment, ratio, and industry-specific items, are standardized across over 180,000 companies to ensure consistency and comparability across different reporting formats. This comprehensive and methodical process enables robust historical analysis and back-testing by seamlessly integrating diverse financial datasets while preserving the granularity of the original reports."
        }
      ],
      "source_indexes": [],
      "card_type": "<string>",
      "content": {
        "cost": 0,
        "data": "<string>",
        "total_rows": 123,
        "truncated": false
      },
      "relevance_score": 123
    }
  ],
  "web_results": [
    {
      "title": "<string>",
      "url": "<string>",
      "snippet": "<string>",
      "source_name": "<string>",
      "publish_date": "<string>",
      "content": {
        "cost": 0,
        "data": "<string>",
        "total_rows": 123,
        "truncated": false
      },
      "citation_number": 123
    }
  ],
  "contents_total_cost": 0
}

​
Notes

  • To authenticate, you’ll need a Tako API key. It’s best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
  • Search returns Tako knowledge cards and web results for a natural language query — the results themselves, with no written answer on top. Use it when you want to render or post-process the cards and web results directly.
  • Want a written answer over the same results? Use Answer — it takes the same request body and adds a synthesized answer.

​
Choosing sources

sources controls where results come from — an object whose keys are the sources to search. A source is searched only if its key is present; omit sources to use the default (both sources, 5 results each):
  • { "data": {} } — Tako knowledge cards from the curated knowledge graph.
  • { "web": {} } — web results.
  • { "data": {}, "web": {} } — both (same as omitting sources).
The legacy value tako is accepted as a synonym for data. Each source takes optional per-source settings: count (1–20, default 5) and include_contents (inline the underlying data). The curated-data source also supports defer_data_retrieval.
A result whose underlying data is downloadable includes a content descriptor. Pass that result’s URL to Contents to download it — a CSV for a Tako card, or extracted text for a web page.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
query
string
required

Natural language search query.

Example:

"Intel vs Nvidia headcount since 2013"

​
effort
enum<string>
default:fast

Search effort level: 'fast' (default), 'instant', or 'deep'.

Available options:
fast,
instant,
deep
​
sources
Sources · object

Per-source settings. An index is searched iff its key is present; defaults to {data:{}, web:{}} (data + web, count 5 each). The legacy key 'tako' is accepted as a synonym for 'data'.

​
country_code
string
default:US

ISO 3166-1 alpha-2 country code for localization.

​
locale
string
default:en-US

BCP-47 locale tag for language/formatting.

​
timezone
string | null

IANA timezone (e.g. 'America/New_York').

​
output_settings
OutputSettings · object

Settings controlling the response shape.

Response

Fast-pipeline search results (Tako cards + web results)

​
request_id
string
required
​
cards
TakoCard · object[]
​
web_results
WebResult · object[]
​
contents_total_cost
number
default:0

Total quoted USD cost of the data inlined on this response — the summed per-fetch price of the results whose payload was populated (one charge per distinct extracted web URL; Tako card CSV is free). This is the QUOTE, not necessarily the amount billed: on a depleted prepaid (PAYG) balance the charge is clamped to the remaining balance, so the amount actually drawn can be less. A result's own cost is a per-fetch quote present whenever it is downloadable, so a result that was requested but whose extraction was skipped or failed still carries its quote; that un-inlined quote is excluded here. 0 when no contents were inlined.