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

# Search

> Search Tako knowledge cards and the web with a natural language query

## Notes

* To authenticate, you'll need a [Tako API key](https://developer.tako.com/console/api-keys). 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](/api-reference/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`.

<Note>
  A result whose underlying data is downloadable includes a `content` descriptor. Pass that result's URL to [Contents](/api-reference/contents) to download it — a CSV for a Tako card, or extracted text for a web page.
</Note>


## OpenAPI

````yaml POST /v3/search
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v3/search:
    post:
      tags:
        - tako
      summary: Search
      description: >-
        Fast-pipeline knowledge search. Returns Tako cards (and web results when
        requested) with no LLM synthesis.
      operationId: search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Fast-pipeline search results (Tako cards + web results)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '408':
          description: The request exceeded the processing time limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
        - apiKey: []
components:
  schemas:
    SearchRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural language search query.
          examples:
            - Intel vs Nvidia headcount since 2013
        effort:
          $ref: '#/components/schemas/SearchEffortLevel'
          description: 'Search effort level: ''fast'' (default), ''instant'', or ''deep''.'
          default: fast
        sources:
          $ref: '#/components/schemas/Sources'
          description: >-
            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:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 country code for localization.
          default: US
        locale:
          type: string
          title: Locale
          description: BCP-47 locale tag for language/formatting.
          default: en-US
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: IANA timezone (e.g. 'America/New_York').
        output_settings:
          anyOf:
            - $ref: '#/components/schemas/OutputSettings'
            - type: 'null'
          description: Settings controlling the response shape.
      additionalProperties: false
      type: object
      required:
        - query
      title: SearchRequest
    SearchResponse:
      properties:
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        web_results:
          items:
            $ref: '#/components/schemas/WebResult'
          type: array
          title: Web Results
        contents_total_cost:
          type: number
          title: Contents Total Cost
          description: >-
            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.
          default: 0
        request_id:
          type: string
          title: Request Id
      type: object
      required:
        - request_id
      title: SearchResponse
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
        - error_message
        - error_type
      title: BaseAPIError
    SearchEffortLevel:
      type: string
      enum:
        - fast
        - instant
        - deep
      title: SearchEffortLevel
      description: >-
        Public effort taxonomy for the new endpoints. FAST is the default.
        INSTANT

        serves cached embeds without re-running data retrieval and is available
        in all

        environments (cannot be combined with
        sources.data.defer_data_retrieval).

        DEEP widens TAKO retrieval and adds an LLM rerank for higher-quality
        results

        (slower; billed at a premium tier). The generated OpenAPI/SDK advertises

        exactly these members, so we add values only as the pipeline gains
        support.
    Sources:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/TakoSourceSettings'
            - type: 'null'
          description: >-
            Tako data source (curated knowledge). Searched iff present. The
            legacy key 'tako' is accepted as a synonym.
        web:
          anyOf:
            - $ref: '#/components/schemas/SourceSettings'
            - type: 'null'
          description: Web source. Searched iff present.
      additionalProperties: false
      type: object
      title: Sources
      description: |-
        Per-source settings. An index is searched iff its field is present.

        The Tako data source is named `data`. The legacy key `tako` is still
        accepted as a synonym (mapped to `data` before validation).
    OutputSettings:
      properties:
        image_dark_mode:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Image Dark Mode
          description: Whether to render card preview images in dark mode.
        force_refresh:
          type: boolean
          title: Force Refresh
          description: >-
            Instant mode only. When false (default), instant returns existing
            cached embeds as-is (fastest) and never writes. When true, instant
            retrieves data for embeds that are missing or stale, then creates or
            refreshes their static embeds — slower for those, but it writes the
            result. Embeds already fresh (within the refresh cadence) are still
            served as-is, not re-retrieved or updated.
          default: false
      additionalProperties: false
      type: object
      title: OutputSettings
    TakoCard:
      properties:
        card_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        semantic_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Semantic Description
        webpage_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webpage Url
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        embed_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Embed Url
        sources:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardSource'
              type: array
            - type: 'null'
          title: Sources
        methodologies:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardMethodology'
              type: array
            - type: 'null'
          title: Methodologies
        source_indexes:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/CardSourceIndex'
                  - $ref: '#/components/schemas/CardSourceIndexSegment'
              type: array
            - type: 'null'
          title: Source Indexes
        card_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Type
        relevance:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeCardRelevance'
            - type: 'null'
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Relevance Score
          description: >-
            Numeric relevance of this card to the query on a 1.0-5.0 scale (5.0
            = exact match; higher is more relevant). Only populated for entitled
            accounts; null otherwise.
      type: object
      title: TakoCard
      description: >-
        A Tako knowledge card on the new search/answer surface. Mirrors the

        legacy KnowledgeCard minus data_url / visualization_data /
        ideal_viz_decisions,

        plus a `content` download descriptor.
    WebResult:
      properties:
        title:
          type: string
          title: Title
          description: Title of the web page.
        url:
          type: string
          title: Url
          description: URL of the web page.
        snippet:
          anyOf:
            - type: string
            - type: 'null'
          title: Snippet
          description: Excerpt(s) from the page that matched the query.
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
          description: Publisher / domain name, when extractable from the URL.
        publish_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Publish Date
          description: Publication date of the page, when available.
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
          description: >-
            Downloadable content descriptor for this result, fetched via the
            Contents endpoint. Web results are always downloadable as text. None
            for callers that do not populate it.
        citation_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Citation Number
          description: >-
            1-based citation number that the answer's inline [N] markers
            reference. Set only when the answer inline-cites this result (the
            Agent API); None on raw-retrieval surfaces.
      type: object
      required:
        - title
        - url
      title: WebResult
      description: |-
        A single raw web search result returned by the WEB source index.

        Distinct from `KnowledgeCardSource` (a citation inside a synthesized
        answer) and `KnowledgeCard` (a Tako visualization). Web results are
        raw retrieval output — title, URL, optional snippet — independent of
        any LLM synthesis that may also happen over them.
    APIErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AUTHENTICATION_ERROR
        - INTERNAL_SERVER_ERROR
        - RELEVANT_RESULTS_NOT_FOUND
        - RATE_LIMIT_EXCEEDED
        - PAYMENT_REQUIRED
        - REQUEST_TIMEOUT
        - FORBIDDEN
        - NOT_FOUND
      title: APIErrorType
    TakoSourceSettings:
      properties:
        count:
          type: integer
          maximum: 20
          minimum: 1
          title: Count
          description: Maximum number of results to return for this source. 1-20.
          default: 5
        include_contents:
          type: boolean
          title: Include Contents
          description: >-
            Inline this source's underlying data (CSV for Tako cards, extracted
            text for web results) directly in the response.
          default: false
        defer_data_retrieval:
          type: boolean
          title: Defer Data Retrieval
          description: >-
            Defer the expensive data-retrieval step: cards return faster with a
            semantic_description and a less detailed description. Mutually
            exclusive with include_contents (cannot inline data that was not
            fetched).
          default: false
      additionalProperties: false
      type: object
      title: TakoSourceSettings
    SourceSettings:
      properties:
        count:
          type: integer
          maximum: 20
          minimum: 1
          title: Count
          description: Maximum number of results to return for this source. 1-20.
          default: 5
        include_contents:
          type: boolean
          title: Include Contents
          description: >-
            Inline this source's underlying data (CSV for Tako cards, extracted
            text for web results) directly in the response.
          default: false
      additionalProperties: false
      type: object
      title: SourceSettings
    KnowledgeCardSource:
      properties:
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
          description: The name of the source
          examples:
            - S&P Global
            - The World Bank
        source_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Description
          description: The description of the source
          examples:
            - >-
              S&P Global is a US-based financial data and analytics company that
              provides products and services to the financial industry.
            - >-
              The World Bank is an international financial institution that
              provides financial and technical assistance to developing
              countries to help them achieve sustainable economic growth and
              improve living conditions.
        source_index:
          anyOf:
            - $ref: '#/components/schemas/CardSourceIndex'
            - $ref: '#/components/schemas/CardSourceIndexSegment'
            - $ref: '#/components/schemas/CardSourcePrivateIndex'
          title: Source Index
          description: The index of the source
          examples:
            - tako
            - web
            - connected_data
            - index_type: connected_data
              segment_id: '123'
            - index_type: connected_data
              private_index_id: '123'
              segment_id: '123'
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL of the source
          examples:
            - https://xignite.com
            - https://stats.com
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
          description: >-
            Raw excerpt(s) retrieved from the source page — the unmodified web
            content the answer was grounded in, NOT the synthesized answer.
            Populated for WEB sources; null for sources that don't carry an
            extracted excerpt (e.g. TAKO sources).
          examples:
            - >-
              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.
      type: object
      required:
        - source_name
        - source_description
        - source_index
        - url
      title: KnowledgeCardSource
    KnowledgeCardMethodology:
      properties:
        methodology_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Name
          description: The name of the methodology
          examples:
            - Where the Data Comes From - S&P Global
        methodology_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Description
          description: The description of the methodology
          examples:
            - >-
              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.
      type: object
      required:
        - methodology_name
        - methodology_description
      title: KnowledgeCardMethodology
    CardSourceIndex:
      type: string
      enum:
        - tako
        - web
        - connected_data
        - tako_deep_v2
      title: CardSourceIndex
    CardSourceIndexSegment:
      properties:
        index_type:
          $ref: '#/components/schemas/CardSourceIndex'
        segment_id:
          type: string
          title: Segment Id
          description: An ID for a segment of a source index
          examples:
            - '123'
      type: object
      required:
        - index_type
        - segment_id
      title: CardSourceIndexSegment
      description: >-
        A segment of a source index. Within a source index, a segment is a
        subset of the data.

        For connected data, a segment is a subset of connected files. A segment
        may be used for

        multi-tenant data e.g. using a segment per customer.
    KnowledgeCardRelevance:
      type: string
      enum:
        - High
        - Medium
        - Low
      title: KnowledgeCardRelevance
    ResultContent:
      properties:
        format:
          $ref: '#/components/schemas/ContentFormat'
        cost:
          type: number
          title: Cost
          default: 0
        data:
          anyOf:
            - type: string
            - type: 'null'
          title: Data
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
        truncated:
          type: boolean
          title: Truncated
          default: false
      type: object
      required:
        - format
      title: ResultContent
      description: >-
        Describes the downloadable content behind a result. `cost` is the USD
        the

        /contents call will charge for this result (Tako card CSV is free; web
        text is

        the canonical Contents rate). The inline fields (`data`/`total_rows`/

        `truncated`) are populated only by auto-contents / `/contents` inline
        mode;

        when unset, this is just the quote (format + cost), fetched later via
        the

        Contents endpoint (a Tako card URL -> ChartConfig -> CSV; any other URL
        ->

        page text).
    CardSourcePrivateIndex:
      properties:
        index_type:
          $ref: '#/components/schemas/CardSourceIndex'
        segment_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment Id
          description: An ID for a segment of a source index (optional for private indexes)
          examples:
            - '123'
        private_index_id:
          type: string
          title: Private Index Id
          description: An ID for a private index
          examples:
            - '123'
      type: object
      required:
        - index_type
        - private_index_id
      title: CardSourcePrivateIndex
    ContentFormat:
      type: string
      enum:
        - csv
        - text
      title: ContentFormat
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````