Skip to main content
POST
/
v1
/
grounding
cURL
curl --request POST \
  --url https://tako.com/api/v1/grounding \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "inputs": {
    "text": "<string>"
  },
  "source_indexes": [],
  "country_code": "US",
  "locale": "en-US",
  "output_settings": {
    "knowledge_card_settings": {
      "image_dark_mode": true
    }
  }
}
'
{
  "answer": "<string>",
  "tako_selected": true,
  "confidence": 3,
  "request_id": "<string>",
  "knowledge_cards": [
    {
      "card_id": "jLmsqH4NfXFLqhWnZqhM",
      "title": "Nvidia, Advanced Micro Devices - Full Time Employees",
      "description": "This is a time series bar chart showing 2 series between 12:00AM UTC-04:00 on 04/01/2013 and 08:55PM UTC on 04/30/2025. Nvidia Full Time Employees latest value was at 12:00AM UTC on 12-31-2024, and had a final value of 36.0K Employees, or 308.72% growth since 12:00AM UTC on 12-31-2013, with a maximum value of 36.0K Employees at 12:00AM UTC on 12-31-2024 and a minimum value of 8.81K Employees at 12:00AM UTC on 12-31-2013; Advanced Micro Devices Full Time Employees latest value was at 12:00AM UTC on 12-31-2024, and had a final value of 28.0K Employees, or 162.39% growth since 12:00AM UTC on 12-31-2013, with a maximum value of 28.0K Employees at 12:00AM UTC on 12-31-2024 and a minimum value of 8.2K Employees at 12:00AM UTC on 12-31-2016. The source of the data is S&P Global. S&P Global is a US-based financial data and analytics company that provides products and services to the financial industry.",
      "webpage_url": "https://tako.com/card/jLmsqH4NfXFLqhWnZqhM/",
      "image_url": "https://tako.com/api/v1/image/jLmsqH4NfXFLqhWnZqhM/",
      "embed_url": "https://tako.com/embed/jLmsqH4NfXFLqhWnZqhM/",
      "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": "The Devil Wears Prada 2 has grossed about $548 million worldwide."
        }
      ],
      "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": "company",
      "data_url": "<string>",
      "relevance": "High",
      "visualization_data": {
        "data": [
          {
            "x": "2013",
            "y": 10000
          },
          {
            "x": "2014",
            "y": 20000
          }
        ],
        "viz_config": {
          "title": "Nvidia, Advanced Micro Devices - Full Time Employees"
        }
      },
      "ideal_viz_decisions": [
        {
          "property_path": "<string>",
          "reason": "<string>",
          "property_path_display_name": "Y-axis tick color"
        }
      ]
    }
  ],
  "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": "The Devil Wears Prada 2 has grossed about $548 million worldwide."
    }
  ],
  "web_results": [
    {
      "title": "<string>",
      "url": "<string>",
      "snippet": "<string>",
      "source_name": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.tako.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
  • Grounding always returns a prose answer and an embeddable card together. Tako constructs the best answer it can and pairs it with a single card in knowledge_cards[0] that you can embed alongside the text. Where Knowledge Search returns one-or-more chart cards as the primary output, grounding’s primary output is the answer — and the card is always there to render with it.
  • Tako includes a self-rated confidence (1–5) so you can gate on quality.

​
Choosing sources

source_indexes controls where the answer is grounded. It must be a non-empty subset of ["tako", "web"]:
  • ["tako"] — answer drawn from Tako’s curated knowledge graph.
  • ["web"] — answer drawn from the live web.
  • ["tako", "web"] — Tako uses both and returns the best-supported answer.

​
Response shape: always a card + answer

Every successful response includes both the prose answer and a single embeddable card in knowledge_cards. knowledge_cards[0] always has a working embed_url and image_url, so clients can render it without branching on response details. 
{
  "answer": "US GDP in 2024 was about $28.8 trillion.",
  "confidence": 5,
  "tako_selected": true,
  "knowledge_cards": [{
    "card_id": "lDeIT6jLJh-UyWEGYuyY",
    "title": "United States GDP",
    "embed_url": "https://trytako.com/embed/lDeIT6jLJh-UyWEGYuyY/",
    "image_url": "https://trytako.com/api/v1/image/lDeIT6jLJh-UyWEGYuyY/",
    "card_type": "card",
    "source_indexes": ["tako"]
  }],
  "sources": [/* ... */],
  "request_id": "..."
}

​
Interpreting the response

  • answer — the grounded text answer.
  • confidence — Tako’s self-rated confidence in the answer, 1 (low) to 5 (high). Use this to gate on quality. A confidence of 1 with an empty answer signals a degraded response — the only case where knowledge_cards may also be empty.
  • knowledge_cards — always populated alongside a non-empty answer. knowledge_cards[0] is the embeddable card paired with the answer; embed_url / image_url work identically regardless of where the answer was drawn from.
  • sources — citations for the answer.
  • tako_selected — provenance hint: true if the answer is backed by a Tako curated card, false if it’s drawn from the live web. Useful for analytics; not required to render the response.
  • web_results — raw web retrieval list when web is in source_indexes, independent of the answer above.
Grounding always runs synchronously and returns HTTP 200 — unlike deep Knowledge Search, there is no search_effort parameter and no async polling.

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Request to the grounding endpoint. Always responds synchronously — there is no search_effort and no async polling.

​
inputs
GroundingInputs · object
required

The query inputs for grounding.

​
source_indexes
enum<string>[]
required

Source indexes to ground the answer in. Must be a non-empty subset of [tako, web]. Tako uses whichever side(s) you list and returns the best-supported answer.

Minimum array length: 1
Available options:
tako,
web,
connected_data,
tako_deep_v2
​
country_code
string
default:US

ISO3166-1 alpha-2 country code (e.g., 'US', 'CA', 'GB').

​
locale
string
default:en-US

Locale for the grounding request.

​
output_settings
KnowledgeSearchRequestOutputSettings · object

Settings for controlling the response shape.

Response

200 - application/json

Grounded answer over Tako, web, or both

Response from the grounding endpoint. Narrower than KnowledgeSearchResults — purpose-built for answer-focused callers.

​
answer
string
required

The grounded text answer.

​
tako_selected
boolean
required

Provenance hint. True if the answer is backed by a Tako curated card; false if it is drawn from the live web (or no source had an on-topic result). Useful for analytics; not required to render the response.

​
confidence
integer
required

Tako's self-rated confidence in the answer (1=low, 5=high). Gate on this for quality. Confidence=1 with an empty answer signals a degraded response.

Required range: 1 <= x <= 5
​
request_id
string
required

Unique ID for this request.

​
knowledge_cards
KnowledgeCard · object[]

Always populated alongside a non-empty answer. knowledge_cards[0] is a single embeddable card paired with the answer — both embed_url and image_url are always set so clients can render it without branching. Empty only on degraded responses (confidence=1 with an empty answer).

​
sources
KnowledgeCardSource · object[]

Citations for the answer.

​
web_results
WebResult · object[] | null

Raw web search results when web is in source_indexes, independent of the answer above — these are the raw retrieval entries.