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

# Dispatch a Retrieval Agent run

> Dispatch a Retrieval Agent run — agentic data retrieval returning structured outputs and cards

The **Retrieval Agent** researches a natural-language question across Tako's knowledge and the live web, then returns schema-defined structured data (`structured_output`) plus visualization `cards` and a cited `answer`. Use it for questions that need real retrieval work — resolving a cohort, ranking or filtering a set, multi-hop aggregation.

See the **[Retrieval Agent guide](/documentation/integrating-tako/agent/retrieval)** for examples, structured outputs, streaming, threads, and sources.

## Notes

* To authenticate, send your [Tako API key](https://tako.com/console/api-keys) in the `X-API-Key` header. Store it as an environment variable rather than hardcoding it.
* The agent is **asynchronous**: this endpoint returns `202` with a `RetrievalAgentRun` whose `status` is `queued`. Poll [Poll a Retrieval Agent run](/api-reference/agent-retrieval-poll) until `status` is `completed` or `failed`.
* To stream progress live instead of polling, send `Accept: text/event-stream`. The response is then a Server-Sent Events stream of `RetrievalAgentStreamEnvelope` events. See the [coding-agent reference](/documentation/integrating-tako/agent/for-coding-agent#stream-live-progress-sse).

## Structured output

Pass an `output_schema` (JSON Schema) to get machine-usable JSON in `result.structured_output`. Mark a property with `"x-tako-dataset": true` to request a **dataset slot**, filled with exact retrieved rows. Supported subset: object/array/string/number/integer/boolean, enum, required, description. Caps: 16 KB, depth 5, 64 properties, 4 dataset slots — violations return `400 output_schema_invalid`.

## Choosing sources

`source_indexes` is optional and defaults to `["data", "web"]` — both. Pass it only to **restrict**: `["data"]` (curated knowledge graph only) or `["web"]` (open web only). The legacy value `"tako"` is a synonym for `"data"`.

## Continuing a thread

Pass the `thread_id` from a prior run to ask a follow-up in the same conversation. Omit it to start a new thread. A thread is pinned to the Retrieval Agent and to one set of `source_indexes`.


## OpenAPI

````yaml POST /v1/agent/retrieval/runs
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:
  /v1/agent/retrieval/runs:
    post:
      tags:
        - agent
      summary: Dispatch a retrieval agent run
      description: >-
        Dispatch a retrieval agent run. Returns 202 with a RetrievalAgentRun
        object. Poll GET /v1/agent/retrieval/runs/{run_id} until status is
        'completed' or 'failed'.
      operationId: createRetrievalAgentRun
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalAgentRunRequest'
      responses:
        '202':
          description: >-
            Run dispatched. With Accept: application/json, poll GET
            /v1/agent/retrieval/runs/{run_id} for the run status. With Accept:
            text/event-stream, the response is an SSE stream of
            RetrievalAgentStreamEnvelope events. The stream ends at stream_done.
            If the stream ends without an agent_result event, poll GET
            /v1/agent/retrieval/runs/{run_id} for the terminal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RetrievalAgentStreamEnvelope'
        '400':
          description: Invalid request (for example, a blank query or a malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '402':
          description: Insufficient API credit balance (PAYG pre-dispatch gate).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '404':
          description: thread_id does not exist or is not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '409':
          description: >-
            Conflict. code is one of: 'conflict' (the thread already has a run
            in flight); 'thread_product_mismatch' (the thread belongs to a
            different agent product); 'source_indexes_mismatch' (a follow-up
            changed the thread's pinned source_indexes).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '500':
          description: Failed to dispatch the agent run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
        - apiKey: []
components:
  schemas:
    RetrievalAgentRunRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural-language data-retrieval request for the retrieval agent.
          examples:
            - S&P 500 semiconductor companies' 2024 revenue and YoY growth
        thread_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Thread Id
          description: Existing thread to continue (follow-up). Omit to start a new thread.
        effort:
          $ref: '#/components/schemas/RetrievalAgentEffort'
          description: Retrieval-agent effort. Only 'medium' is currently supported.
          default: medium
        source_indexes:
          items:
            type: string
            enum:
              - data
              - web
          type: array
          title: Source Indexes
          description: >-
            Which sources the agent may use: 'data' (curated knowledge), 'web'
            (open-web search), or both. Defaults to ['data', 'web']. Tako
            accepts the legacy value 'tako' as a synonym for 'data'.
          examples:
            - - data
            - - web
            - - data
              - web
        cards:
          type: boolean
          title: Cards
          description: >-
            Whether the agent may build visualization cards. The default is true
            and permissive: the agent may build cards, but it does not have to
            (a completed run with no cards is legitimate). Set false to suppress
            card building entirely.
          default: true
        output_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Schema
          description: >-
            JSON Schema for structured output. The agent writes the synthesized
            fields. Dataset slots (marked with x-tako-dataset: true) receive
            exact retrieved rows as a TakoDataset. Supported subset: the object,
            array, string, number, integer, and boolean types, plus enum,
            required, and description. Caps: 16KB, depth 5, 64 properties, 4
            dataset slots. Violations return 400 output_schema_invalid.
        locale:
          type: string
          title: Locale
          description: >-
            BCP-47 locale. Drives the language of the agent's answer and the
            locale used when rendering card preview images. Defaults to en-US.
          default: en-US
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: >-
            IANA timezone (for example, 'America/New_York'). The agent uses it
            to render dates and times in card preview images. It does not affect
            the returned data.
        output_settings:
          anyOf:
            - $ref: '#/components/schemas/AgentOutputSettings'
            - type: 'null'
          description: Settings that control the response and rendering.
      type: object
      required:
        - query
      title: RetrievalAgentRunRequest
      description: Request body for POST /v1/agent/retrieval/runs.
    RetrievalAgentRun:
      properties:
        run_id:
          type: string
          title: Run Id
        object:
          type: string
          const: agent.retrieval.run
          title: Object
          default: agent.retrieval.run
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
        result:
          anyOf:
            - $ref: '#/components/schemas/RetrievalAgentResult'
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        request:
          anyOf:
            - $ref: '#/components/schemas/RetrievalAgentRunRequest'
            - type: 'null'
      type: object
      required:
        - run_id
        - status
        - created_at
      title: RetrievalAgentRun
      description: >-
        The retrieval-agent run resource returned by dispatch (202) and poll
        (GET).
    RetrievalAgentStreamEnvelope:
      properties:
        seq:
          type: integer
          minimum: 0
          title: Seq
        run_id:
          type: string
          title: Run Id
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        category:
          $ref: '#/components/schemas/StreamCategory'
        block:
          oneOf:
            - $ref: '#/components/schemas/ToolCallEvent'
            - $ref: '#/components/schemas/ToolResultEvent'
            - $ref: '#/components/schemas/ToolErrorEvent'
            - $ref: '#/components/schemas/ToolRetryEvent'
            - $ref: '#/components/schemas/StatusEvent'
            - $ref: '#/components/schemas/SubagentEvent'
            - $ref: '#/components/schemas/ReasoningEvent'
            - $ref: '#/components/schemas/TextEvent'
            - $ref: '#/components/schemas/DataPipelineAnswerEvent'
            - $ref: '#/components/schemas/RetrievalAgentResultEvent'
            - $ref: '#/components/schemas/RunSummaryEvent'
            - $ref: '#/components/schemas/HeartbeatEvent'
            - $ref: '#/components/schemas/StreamResetEvent'
            - $ref: '#/components/schemas/StreamDoneEvent'
          title: Block
          discriminator:
            propertyName: kind
            mapping:
              agent_result:
                $ref: '#/components/schemas/RetrievalAgentResultEvent'
              data_pipeline_answer:
                $ref: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat:
                $ref: '#/components/schemas/HeartbeatEvent'
              reasoning:
                $ref: '#/components/schemas/ReasoningEvent'
              run_summary:
                $ref: '#/components/schemas/RunSummaryEvent'
              status:
                $ref: '#/components/schemas/StatusEvent'
              stream_done:
                $ref: '#/components/schemas/StreamDoneEvent'
              stream_reset:
                $ref: '#/components/schemas/StreamResetEvent'
              subagent:
                $ref: '#/components/schemas/SubagentEvent'
              text:
                $ref: '#/components/schemas/TextEvent'
              tool_call:
                $ref: '#/components/schemas/ToolCallEvent'
              tool_error:
                $ref: '#/components/schemas/ToolErrorEvent'
              tool_result:
                $ref: '#/components/schemas/ToolResultEvent'
              tool_retry:
                $ref: '#/components/schemas/ToolRetryEvent'
      type: object
      required:
        - seq
        - run_id
        - category
        - block
      title: RetrievalAgentStreamEnvelope
      description: |-
        Public SSE envelope for the Retrieval Agent run stream. It has the same
        wire shape as AgentStreamEnvelope. The only difference is that the
        terminal agent_result block carries RetrievalAgentResult (unified
        top-level citations, no web_results), so the SSE terminal matches the
        GET poll result.
    ErrorObject:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ErrorObject
    RetrievalAgentEffort:
      type: string
      enum:
        - medium
      title: RetrievalAgentEffort
      description: |-
        Effort taxonomy for the Retrieval Agent (POST /v1/agent/retrieval/runs).

        Only 'medium' is available today. `effort` stays a request field for
        forward compatibility and for parity with AnswerAgentEffort. The values
        'low' and 'high' return 400 at validation.
    AgentOutputSettings:
      properties:
        image_dark_mode:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Image Dark Mode
          description: >-
            Render card preview images in dark mode. Omit to use the default
            (dark).
      type: object
      title: AgentOutputSettings
    AgentRunStatus:
      type: string
      enum:
        - queued
        - running
        - completed
        - failed
      title: AgentRunStatus
    RetrievalAgentResult:
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        citations:
          items:
            $ref: '#/components/schemas/AgentAnswerCitation'
          type: array
          title: Citations
        metadata:
          anyOf:
            - $ref: '#/components/schemas/AgentAnswerMetadata'
            - type: 'null'
        structured_output:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Structured Output
          description: >-
            Caller-shaped structured output (present only if the request carried
            output_schema and status is not 'failed'). Dataset slots contain a
            TakoDataset envelope of exact retrieved rows, or null when the agent
            left them unfilled.
        structured_output_status:
          anyOf:
            - $ref: '#/components/schemas/StructuredOutputStatus'
            - type: 'null'
          description: >-
            complete | partial | failed. Present when the request supplied
            output_schema and the run reached the finalize step. It can be
            absent when the whole run failed or timed out before finalize; the
            run-level status and error convey that, and the echoed
            request.output_schema still identifies the run as structured.
        structured_output_citations:
          anyOf:
            - additionalProperties:
                items:
                  type: integer
                type: array
              type: object
            - type: 'null'
          title: Structured Output Citations
          description: >-
            Best-effort field-path -> citation-index map joining the top-level
            citations registry (same [n] index space as the answer). Absent when
            status is 'failed'.
        unfilled_fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Unfilled Fields
          description: >-
            Dot-separated paths of unfilled dataset slots; present only if
            status is 'partial'.
        structured_output_error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
          description: Why structured output failed; present only if status is 'failed'.
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
      type: object
      title: RetrievalAgentResult
      description: |-
        Final retrieval-agent output. answer is markdown prose with [n]
        citation markers. cards reuse the sibling TakoCard. citations is the
        unified top-level registry for data and web sources — there is no
        web_results field. metadata carries definitions, assumptions, and
        methodology. The structured_output_* fields carry the caller-shaped
        output_schema result; they are present only if the request supplied
        output_schema. See each field's description for the exact presence
        rules.
    Usage:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: >-
            Total quoted USD cost of this request. Sum of compute cost and data
            cost.
        compute:
          anyOf:
            - $ref: '#/components/schemas/UsageCompute'
            - type: 'null'
          description: >-
            Compute cost breakdown. Present only on surfaces with a compute step
            (absent for contents).
        data:
          anyOf:
            - $ref: '#/components/schemas/UsageData'
            - type: 'null'
          description: >-
            Inline-data cost breakdown. Present only when the surface emitted
            billable inline data.
      type: object
      required:
        - total_cost_usd
      title: Usage
      description: |-
        Usage for one metered request. `total_cost_usd` is always present (the
        total quoted charge). `compute` and `data` are the additive breakdown;
        each appears only where it applies. total_cost_usd always equals the sum
        of the components that appear.
    StreamCategory:
      type: string
      enum:
        - content
        - activity
        - control
      title: StreamCategory
    ToolCallEvent:
      properties:
        kind:
          type: string
          const: tool_call
          title: Kind
          default: tool_call
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        status_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Message
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - tool
      title: ToolCallEvent
    ToolResultEvent:
      properties:
        kind:
          type: string
          const: tool_result
          title: Kind
          default: tool_result
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        elapsed_ms:
          type: integer
          title: Elapsed Ms
          default: 0
        link:
          anyOf:
            - type: string
            - type: 'null'
          title: Link
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
      title: ToolResultEvent
    ToolErrorEvent:
      properties:
        kind:
          type: string
          const: tool_error
          title: Kind
          default: tool_error
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        error:
          type: string
          title: Error
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
        - error
      title: ToolErrorEvent
    ToolRetryEvent:
      properties:
        kind:
          type: string
          const: tool_retry
          title: Kind
          default: tool_retry
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        error:
          type: string
          title: Error
        elapsed_ms:
          type: integer
          title: Elapsed Ms
          default: 0
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
        - error
      title: ToolRetryEvent
    StatusEvent:
      properties:
        kind:
          type: string
          const: status
          title: Kind
          default: status
        message:
          type: string
          title: Message
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - message
      title: StatusEvent
    SubagentEvent:
      properties:
        kind:
          type: string
          const: subagent
          title: Kind
          default: subagent
        agent_id:
          type: string
          title: Agent Id
        subagent_type:
          type: string
          title: Subagent Type
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
        event:
          type: string
          enum:
            - dispatch
            - complete
          title: Event
      type: object
      required:
        - agent_id
        - subagent_type
        - event
      title: SubagentEvent
    ReasoningEvent:
      properties:
        kind:
          type: string
          const: reasoning
          title: Kind
          default: reasoning
        id:
          type: string
          title: Id
        delta:
          type: string
          title: Delta
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - delta
      title: ReasoningEvent
    TextEvent:
      properties:
        kind:
          type: string
          const: text
          title: Kind
          default: text
        id:
          type: string
          title: Id
        delta:
          type: string
          title: Delta
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - delta
      title: TextEvent
    DataPipelineAnswerEvent:
      properties:
        kind:
          type: string
          const: data_pipeline_answer
          title: Kind
          default: data_pipeline_answer
        id:
          type: string
          title: Id
        chart_refs:
          items:
            type: string
          type: array
          title: Chart Refs
      type: object
      required:
        - id
      title: DataPipelineAnswerEvent
      description: |-
        Signals that the data pipeline produced one or more charts for the
        answer. It carries only chart references. The answer text streams in
        `text` events, and the structured result arrives in the terminal
        `agent_result` event, not here.
    RetrievalAgentResultEvent:
      properties:
        kind:
          type: string
          const: agent_result
          title: Kind
          default: agent_result
        id:
          type: string
          title: Id
        data:
          $ref: '#/components/schemas/RetrievalAgentResult'
      type: object
      required:
        - id
        - data
      title: RetrievalAgentResultEvent
    RunSummaryEvent:
      properties:
        kind:
          type: string
          const: run_summary
          title: Kind
          default: run_summary
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
      type: object
      required:
        - status
        - created_at
      title: RunSummaryEvent
      description: >-
        Terminal run metadata. The stream emits it once, immediately before

        stream_done. It mirrors the GET-poll run fields that the stream
        otherwise

        lacks; the result stays in the agent_result event. status, created_at,

        and completed_at are always present. error appears only on failure.
        usage

        appears only on metered (pay-as-you-go) runs and is null otherwise.

        agent_result plus run_summary equals the GET poll object.


        It carries the same envelope `seq` as the stream_done that follows it
        (it

        has no seq of its own), and the stream suppresses its SSE `id:`, so it

        advances no resume cursor. Identify it by `kind`; never assume `seq` is

        unique per frame.
    HeartbeatEvent:
      properties:
        kind:
          type: string
          const: heartbeat
          title: Kind
          default: heartbeat
      type: object
      title: HeartbeatEvent
    StreamResetEvent:
      properties:
        kind:
          type: string
          const: stream_reset
          title: Kind
          default: stream_reset
      type: object
      title: StreamResetEvent
    StreamDoneEvent:
      properties:
        kind:
          type: string
          const: stream_done
          title: Kind
          default: stream_done
      type: object
      title: StreamDoneEvent
    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/TakoCardSource'
              type: array
            - type: 'null'
          title: Sources
        methodologies:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardMethodology'
              type: array
            - type: 'null'
          title: Methodologies
        source_indexes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoSourceIndex'
              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'
        exportable:
          type: boolean
          title: Exportable
          description: >-
            Whether the /contents endpoint can download this card's data. false
            means the export is not available; use the card's chart and inline
            preview instead. true means the export is eligible but not
            guaranteed; the /contents endpoint can still return 403, so fall
            back to the preview on error.
          default: false
        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.
        nodes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoCardNode'
              type: array
            - type: 'null'
          title: Nodes
          description: >-
            Graph nodes (entities and metrics) behind this card. The response
            includes them by default. Absent for web-only cards or when node
            resolution was not available. Use each id with /v1/graph/node/{id}
            for full detail (aliases, subtype), or pass ids in
            sources.data.node_ids to pin these nodes in future searches.
        metric_definitions:
          anyOf:
            - items:
                $ref: '#/components/schemas/MetricDefinition'
              type: array
            - type: 'null'
          title: Metric Definitions
          description: >-
            Definitions of the metrics this card displays (name + definition).
            Null when no displayed metric has a definition available.
        data_freshness:
          anyOf:
            - $ref: '#/components/schemas/DataFreshness'
            - type: 'null'
          description: >-
            Freshness dates for the card's data: the coverage date (data_as_of)
            and the last refresh date (last_updated). Null when neither date is
            available.
      type: object
      title: TakoCard
      description: |-
        A Tako knowledge card on the search and answer surfaces. It carries a
        `content` download descriptor.
    AgentAnswerCitation:
      properties:
        index:
          type: integer
          title: Index
        title:
          type: string
          title: Title
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
        source_index:
          anyOf:
            - $ref: '#/components/schemas/TakoSourceIndex'
            - type: 'null'
        excerpt:
          anyOf:
            - type: string
            - type: 'null'
          title: Excerpt
        publish_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Publish Date
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
      type: object
      required:
        - index
        - title
      title: AgentAnswerCitation
      description: >-
        One indexed source behind the answer. Every inline [n] marker in the

        answer joins to a citation's index. A citation can also back the answer

        without a surviving inline marker — markers map to citations, not 1:1.

        This covers web and Tako sources alike, and it is the single shared

        citation object across both agent products. The extended fields

        (source_index, excerpt, publish_date, content) are additive and
        nullable.

        The Answer Agent populates source_index and leaves the rest null. The

        Retrieval Agent also populates excerpt and publish_date for web

        sources.
    AgentAnswerMetadata:
      properties:
        citations:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerCitation'
              type: array
            - type: 'null'
          title: Citations
        definitions:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerDefinition'
              type: array
            - type: 'null'
          title: Definitions
        assumptions:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerAssumption'
              type: array
            - type: 'null'
          title: Assumptions
        methodology:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerMethodologyNote'
              type: array
            - type: 'null'
          title: Methodology
      type: object
      title: AgentAnswerMetadata
      description: |-
        Supplementary answer metadata. All fields are optional — population
        varies by effort and engine (low fills citations only today). Tako adds
        new components here additively.
    StructuredOutputStatus:
      type: string
      enum:
        - complete
        - partial
        - failed
      title: StructuredOutputStatus
      description: Terminal status of the structured-output channel.
    UsageCompute:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of running the operation.
      type: object
      required:
        - cost_usd
      title: UsageCompute
      description: |-
        The cost of running the operation. Absent on surfaces with no compute
        step (contents).
    UsageData:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of the inline data delivered in the response.
        datasets:
          type: integer
          title: Datasets
          description: Number of billed data units (datasets) included in the response.
      type: object
      required:
        - cost_usd
        - datasets
      title: UsageData
      description: |-
        The cost and quantity of inline data delivered in the response: the
        agent per-dataset surcharge, the search and answer include_contents
        charge, or the contents per-item cost. `datasets` is the count of billed
        data units. Absent when the surface did not or cannot emit inline data
        (for example, the answer agent).
    TakoCardSource:
      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
        source_index:
          $ref: '#/components/schemas/TakoSourceIndex'
          description: The index of the source
          examples:
            - data
            - web
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL of the source
          examples:
            - https://xignite.com
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
          description: >-
            Raw excerpts retrieved from the source page — the unmodified web
            content that grounded the answer. Present for WEB sources; null for
            DATA sources.
      type: object
      required:
        - source_index
      title: TakoCardSource
      description: |-
        A source that backs a TakoCard on the SDK surfaces. It uses the
        {data, web} TakoSourceIndex taxonomy.
    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: >-
            A concise, one-sentence summary of the methodology: the source and
            what it measures. When no concise summary is available, this carries
            the full methodology text.
          examples:
            - >-
              Financial metrics standardized by S&P Global from company
              regulatory filings, press releases, and restatements.
      type: object
      required:
        - methodology_name
        - methodology_description
      title: KnowledgeCardMethodology
    TakoSourceIndex:
      type: string
      enum:
        - data
        - web
      title: TakoSourceIndex
      description: |-
        Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,
        agent). It is symmetric with the request taxonomy {data, web}.
    KnowledgeCardRelevance:
      type: string
      enum:
        - High
        - Medium
        - Low
      title: KnowledgeCardRelevance
    ResultContent:
      properties:
        content_format:
          anyOf:
            - $ref: '#/components/schemas/ContentsFormat'
            - type: 'null'
          description: >-
            Serialization of the returned card data: 'csv', 'json_records',
            'json_compact', or 'card_json'. Null for web text (always returned
            as raw text) and for a quote-only response (nothing was serialized).
        cost:
          type: number
          title: Cost
          description: >-
            Price of this item in USD. On a /contents response this is the
            amount actually billed. On a quote_only response it is a prospective
            /contents export price, because Tako fetched nothing and billed
            nothing. On a search or answer downloadable card it is also a
            prospective price, unless Tako returned more rows than the free row
            allowance; then it is the amount this response billed for the card.
            Use export_pricing on its own to price a /contents export of the
            same card. Do not add this value to that result: a billed inline
            card uses the caller's own inline free row allowance, and
            export_pricing uses the /contents free row allowance.
          default: 0
        data:
          anyOf:
            - type: string
            - type: 'null'
          title: Data
          description: >-
            Inline payload as text: card data serialized to CSV, or a web page's
            extracted text. Set only for the 'csv' card format and for web text;
            null otherwise.
        records:
          anyOf:
            - items:
                additionalProperties:
                  anyOf:
                    - type: string
                    - type: number
                    - type: integer
                    - type: boolean
                    - type: 'null'
                type: object
              type: array
            - type: 'null'
          title: Records
          description: >-
            Inline card data as verbose JSON: a list of row objects keyed by
            column name. Set only when content_format is 'json_records'.
        dataset:
          anyOf:
            - $ref: '#/components/schemas/TakoDataset'
            - type: 'null'
          description: >-
            Inline card data as a compact TakoDataset (typed column headers plus
            positional row arrays). Set only when content_format is
            'json_compact'.
        card_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Card Data
          description: >-
            Inline card data as a card-type-specific JSON object. The
            'card_type' field inside the object names its shape. Set only when
            content_format is 'card_json'. The payload is always complete:
            card_json is never truncated. Card types without a card_json shape
            return 422 on /contents and fall back to 'json_compact' on search
            and answer include_contents.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            Presigned download URL for the content, returned in 'url' delivery
            mode. Null for inline delivery and for quotes; pair with expires_at.
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Expires At
          description: >-
            ISO-8601 timestamp after which the presigned url stops working. Null
            whenever url is null.
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
          description: >-
            True total number of rows in the card's data, independent of how
            many rows were returned. Compare with truncated to tell whether more
            rows are available via a larger max_rows. Null for web text.
        truncated:
          type: boolean
          title: Truncated
          description: >-
            True when Tako capped the returned rows and total_rows is larger
            than the number returned. Tako caps a card at the request max_rows
            or at the 2,000-row system ceiling. On a search or answer response,
            Tako also applies a budget of 2,000 billable rows that all cards in
            the response share, so it can return fewer rows for a later card
            than max_rows asked for. Rows within the free row allowance do not
            use that budget, so a request that omits max_rows is never capped by
            it.
          default: false
        export_pricing:
          anyOf:
            - $ref: '#/components/schemas/ExportPricing'
            - type: 'null'
          description: >-
            Rate card for a downloadable card CSV, so a caller can compute a
            full export's cost before fetching. Null for web text and other
            non-downloadable content.
        manifest:
          anyOf:
            - items:
                $ref: '#/components/schemas/ColumnDescriptor'
              type: array
            - type: 'null'
          title: Manifest
          description: >-
            Per-column metadata, one entry per exported column, in column order:
            entry i describes column i (CSV header i, json_records key i, or
            dataset.columns[i]). Each entry carries name (the column header),
            dtype, unit, metric, and entity. Null for web or quote responses
            that carry no tabular columns.
      type: object
      title: ResultContent
      description: >-
        Describes the downloadable content behind a result.


        Pricing: for a Tako card CSV export, the charge is a flat per-export

        baseline plus a per-source, per-row CPM on the rows returned beyond the

        free row allowance. Web text bills at the standard Contents rate.


        The meaning of `cost` depends on the surface. On `/contents` responses,

        `cost` is the actual charge, and it reconciles with what that response

        billed. The exception is a `quote_only` response, where `cost` is a

        prospective price: Tako neither fetched nor billed the export, and the

        payload and url fields are null. On a search or answer downloadable

        card, `cost` is a prospective `/contents` quote (the per-export baseline

        floor) unless Tako returned more rows than the caller's free row

        allowance, in which case it is what this response billed for the card.
        The

        billed cards sum to `usage.data.cost_usd`, never to

        `usage.total_cost_usd` (which always adds the flat per-request compute

        rate), and only when no web contents were inlined, because every web
        fetch

        charge lands in that same `data` field.


        `export_pricing` carries the `/contents` export rate, so a caller can

        compute the full charge of a later export before fetching: baseline_usd
        +

        row_cpm_usd * max(0, rows - free_rows) / 1000, with rows <=

        max_rows_ceiling. The `max_rows_ceiling` bound does NOT hold for

        `content_format=card_json`, which has no row cap: the baseline and CPM
        terms

        stay exact, but a card_json payload with more record rows than

        `max_rows_ceiling` bills every one of them. Read `total_rows` on a
        delivered

        card_json response, or send `quote_only`, for its exact cost. That rate

        always uses the `/contents` free row allowance,

        whatever the caller's inline allowance is, because `/contents` has no

        entitlement concept. `export_pricing` is null for web text and

        non-downloadable content.


        Do NOT combine `cost` with `export_pricing` on a billed inline card.
        There,

        `cost` is the amount THIS response charged, computed against the
        caller's

        own inline free row allowance, so it is not a `/contents` price. For a

        caller whose inline allowance is larger than the `/contents` allowance
        the

        two fields disagree, because the inline charge starts above the larger

        allowance and the published `/contents` formula starts above the smaller

        one. Read `cost` for what this response billed. Use `export_pricing`
        alone

        to price a `/contents` export of the same card.


        Tako populates exactly one payload group once it delivers contents:

        `data` (CSV or web text), `records` (verbose JSON), `dataset` (compact

        TakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus

        `expires_at` (presigned download).

        `content_format` names the serialization; it is null for web text and

        for an undelivered quote. When every payload field is unset, this is

        just the quote (`cost`); fetch the content later via the Contents

        endpoint.
    TakoCardNode:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Opaque, human-friendly public id (<prefix>::<name>::<hash>, where
            prefix is ent for an entity or mt for a metric). Ids are not durable
            across knowledge-graph rebuilds — resolve them at request time
            rather than storing them.
        type:
          $ref: '#/components/schemas/GraphNodeType'
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - id
        - type
        - name
      title: TakoCardNode
      description: |-
        Slim graph node for the search and answer card surface
        (TakoCard.nodes). It is deliberately narrower than GraphNode: it carries
        no `aliases` and no `subtype`. Callers that need the full node resolve
        the id via /v1/graph/node/{id}.
    MetricDefinition:
      properties:
        name:
          type: string
          title: Name
          description: The metric's display name
          examples:
            - Gross Domestic Product (current US$)
        definition:
          type: string
          title: Definition
          description: Human-readable definition of the metric
      type: object
      required:
        - name
        - definition
      title: MetricDefinition
      description: |-
        Definition of a metric shown on a card. Sourced from the metric's
        ValueType definition — the same text as the in-app methodology 'Metrics'
        tab.
    DataFreshness:
      properties:
        data_as_of:
          anyOf:
            - type: string
            - type: 'null'
          title: Data As Of
          description: >-
            Date of the most recent observation in the card's data, as an ISO
            date (YYYY-MM-DD). Null for card types without a coverage date.
          examples:
            - '2026-06-30'
        last_updated:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated
          description: >-
            Date Tako last refreshed the underlying data, as an ISO date
            (YYYY-MM-DD).
          examples:
            - '2026-07-14'
      type: object
      title: DataFreshness
      description: |-
        When the card's data was last observed and last refreshed. Either field
        may be null when that date isn't available for the card type.
    AgentAnswerDefinition:
      properties:
        term:
          type: string
          title: Term
        definition:
          type: string
          title: Definition
        source_ref:
          anyOf:
            - type: integer
            - type: 'null'
          title: Source Ref
      type: object
      required:
        - term
        - definition
      title: AgentAnswerDefinition
    AgentAnswerAssumption:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        source_ref:
          anyOf:
            - type: integer
            - type: 'null'
          title: Source Ref
      type: object
      required:
        - title
        - description
      title: AgentAnswerAssumption
    AgentAnswerMethodologyNote:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
      type: object
      required:
        - title
        - description
      title: AgentAnswerMethodologyNote
    ContentsFormat:
      type: string
      enum:
        - csv
        - json_records
        - json_compact
        - card_json
      title: ContentsFormat
      description: >-
        Serialization of tabular (Tako card) data. Web content is always raw
        text

        and carries no content format (content_format is null).
    TakoDataset:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TakoDatasetColumn'
          type: array
          title: Columns
          description: Ordered column headers (name + type), one per position in every row.
        rows:
          items:
            items:
              anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - type: 'null'
            type: array
          type: array
          title: Rows
          description: >-
            Row data as positional cell arrays aligned to `columns` order. Cells
            are string/number/boolean/null; nulls are preserved, never coerced.
        total_rows:
          type: integer
          title: Total Rows
          description: >-
            True total number of rows in the underlying data, before any
            truncation.
        truncated:
          type: boolean
          title: Truncated
          description: >-
            True when `rows` was capped and total_rows exceeds the number
            returned.
        ref:
          type: string
          title: Ref
          description: Source URL the dataset was derived from (e.g. the Tako card URL).
        sources:
          items:
            $ref: '#/components/schemas/TakoDatasetSource'
          type: array
          title: Sources
          description: 'Provenance for the dataset: the sources the rows were drawn from.'
        provenance:
          type: string
          enum:
            - query
            - web_extraction
          title: Provenance
          description: 'How the rows were produced: ''query'' (Tako data) or ''web_extraction''.'
          default: query
      type: object
      required:
        - columns
        - rows
        - total_rows
        - truncated
        - ref
        - sources
      title: TakoDataset
      description: |-
        The dataset-slot envelope: exact retrieved rows as positional arrays
        in `columns` order. The rows come directly from the data source; the LLM
        never transcribes them.
    ExportPricing:
      properties:
        baseline_usd:
          type: number
          title: Baseline Usd
          description: Flat USD charged once per card export, independent of row count.
        row_cpm_usd:
          type: number
          title: Row Cpm Usd
          description: >-
            USD charged per 1,000 rows on rows beyond the free allowance
            (free_rows). Card-level total across the card's priced sources; no
            per-source breakdown.
        free_rows:
          type: integer
          title: Free Rows
          description: >-
            Rows included at the baseline price before the per-1,000-row rate
            (row_cpm_usd) begins to apply. This is the /contents free row
            allowance. It is not the inline free row allowance of a search or
            answer response, which can be larger.
        max_rows_ceiling:
          type: integer
          title: Max Rows Ceiling
          description: >-
            Hard cap on rows a single export can return and bill; a larger
            requested max_rows is clamped to this. Applies to the row-based
            formats (csv, json_records, json_compact) only. A card_json export
            is a semantic document with no row cap: it bills every record row,
            so above this number the formula understates the charge. Send
            quote_only for an exact card_json price.
      type: object
      required:
        - baseline_usd
        - row_cpm_usd
        - free_rows
        - max_rows_ceiling
      title: ExportPricing
      description: >-
        Card-CSV export pricing RATE for the /contents endpoint, published so a

        caller can compute an export's cost before fetching. A /contents export

        charge = baseline_usd + row_cpm_usd * max(0, rows - free_rows) / 1000,

        rows <= max_rows_ceiling. row_cpm_usd is the card-level total (sum of
        the

        card's distinct priced sources' per-1,000-row rate); no per-source
        breakdown.


        This formula reproduces a /contents export charge ONLY. `free_rows` here
        is

        always the /contents free row allowance. It does not reproduce the
        `cost` of

        a billed inline card on a search or answer response, because that charge
        uses

        the caller's own inline free row allowance, which can be larger.
    ColumnDescriptor:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        metric:
          anyOf:
            - type: string
            - type: 'null'
          title: Metric
        entity:
          anyOf:
            - type: string
            - type: 'null'
          title: Entity
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
        dtype:
          anyOf:
            - $ref: '#/components/schemas/TakoDatasetColumnType'
            - type: 'null'
      type: object
      title: ColumnDescriptor
      description: >-
        Structured description of one exported value column.


        Producers set the semantic parts they know (``metric``, ``entity``,

        ``unit``). ``name`` and ``dtype`` are filled centrally: ``name`` is the

        rendered canonical header (set by ``apply_descriptor_names``), and
        ``dtype``

        is inferred from the real column data in ``finalize_export_frame``. A

        producer-set ``dtype`` would drift from the cells, and a producer cannot
        know

        the disambiguated ``name`` before the whole frame is rendered.


        In the exported manifest ``name`` equals the column's actual header, and
        the

        manifest is positionally aligned with the exported columns (manifest
        entry

        ``i`` describes column ``i``).
    GraphNodeType:
      type: string
      enum:
        - metric
        - entity
      title: GraphNodeType
    TakoDatasetColumn:
      properties:
        name:
          type: string
          title: Name
          description: Column name.
        type:
          $ref: '#/components/schemas/TakoDatasetColumnType'
          description: >-
            Logical column type: 'string', 'number', 'boolean', 'date', or
            'datetime'. Temporal cells are ISO-8601 strings.
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
          description: >-
            Structured unit for the column values, e.g. 'USD billions', '%'.
            Null when unitless.
      type: object
      required:
        - name
        - type
      title: TakoDatasetColumn
      description: Typed header entry; `type` is the JSON-facing column type.
    TakoDatasetSource:
      properties:
        name:
          type: string
          title: Name
          description: Human-readable source name (e.g. 'FRED', 'S&P Global').
        index:
          type: string
          enum:
            - data
            - web
          title: Index
          description: 'Source index the rows came from: ''data'' (Tako) or ''web''.'
          default: data
      type: object
      required:
        - name
      title: TakoDatasetSource
      description: |-
        Per-dataset provenance entry. `index` names the source index, not a
        citation display number. It is "data" for every dataset today — web
        content never fills a dataset slot.
    TakoDatasetColumnType:
      type: string
      enum:
        - string
        - number
        - boolean
        - date
        - datetime
      title: TakoDatasetColumnType
      description: |-
        Logical column type declared in a TakoDataset header. Temporal cells
        are ISO-8601 strings. Each column declares 'date' or 'datetime' on its
        own: a temporal column whose non-null values are all timezone-naive
        midnights declares 'date'.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````