Skip to main content
POST
/
v1
/
knowledge_search
cURL
curl --request POST \
  --url https://tako.com/api/v1/knowledge_search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "inputs": {
    "text": "Intel vs Nvidia headcount since 2013"
  },
  "source_indexes": [
    "tako"
  ],
  "output_settings": {
    "knowledge_card_settings": {
      "image_dark_mode": true
    }
  },
  "country_code": "US",
  "locale": "en-US",
  "search_effort": "fast"
}
'
{
  "outputs": {
    "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"
          }
        ]
      }
    ],
    "answer": "<string>"
  },
  "request_id": "<string>"
}

​
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.
  • This endpoint executes a Tako Knowledge Search using a natural language query. Tako parses and interprets the query, and then assembles knowledge cards on the fly in response.
  • If the query requests multiple series of data (i.e. “Tesla Stock Price vs Net Income”), Tako will adjust the knowlkedge cards so it matches the user’s intent. This may necessitate using both a left and right y-axis to visualize data of far different dimensions/magnitudes, applying aggregations (e.g. percent change since start y-axis when there are series with distinct unit types), or other transformations.
Deep search returns 202 instead of 200. If search_effort is deep (or auto that resolves to deep), this endpoint returns HTTP 202 with a task_id for async polling instead of blocking. Deep search exceeds the sync timeout, so it is transparently delegated to the async pipeline. Poll /v1/knowledge_search/async/status/?task_id=<task_id> for results. See the Deep Search guide for details.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
inputs
KnowledgeSearchInputs · object
required

The inputs for the knowledge search request

​
source_indexes

The priority order of potential source indexes to search. Once relevant results are found in a source index, the search will stopand results from remaining source indexes will not be searched.

Available options:
tako,
web,
connected_data,
tako_deep_v2
​
output_settings
KnowledgeSearchRequestOutputSettings · object

Settings for controlling outputs of the knowledge search request

​
country_code
string
default:US

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

​
locale
string
default:en-US

Locale for the knowledge search request

​
search_effort
enum<string> | null

The effort to put into the search. Controls the depth and latency of the search pipeline. Deep search returns 202 with async polling.

Available options:
fast,
medium,
deep,
auto
Example:

"fast"

Response

200 - application/json

List of knowledge search results

​
outputs
KnowledgeSearchOutputs · object
​
request_id
string | null