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

# Poll a Company Agent run

> Retrieve the current state and result of a Company Agent run

## Notes

* Poll with the `run_id` returned by [Dispatch a Company Agent run](/api-reference/agent-company-dispatch). `status` progresses `queued` → `running` → `completed` / `failed`. The `result` is populated once `status` is `completed`.
* The result carries `answer`, `cards` and `citations`. Each list is a card: export it through [Contents](/api-reference/contents) to get its rows, with `premium` set to `true` to reveal its contacts.
* To resume or tail the run as a live Server-Sent Events stream, send `Accept: text/event-stream`. Use `starting_after` (or the `Last-Event-ID` header) to replay only events whose `seq` is greater than a value you've already seen.


## OpenAPI

````yaml GET /v1/agent/company/runs/{run_id}
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/company/runs/{run_id}:
    get:
      tags:
        - agent
      summary: Poll a company agent run
      description: >-
        Retrieve the current state of a company agent run. Poll until status is
        'completed' or 'failed'. The response includes result when status is
        'completed'.
      operationId: getCompanyAgentRun
      parameters:
        - description: The run ID from the POST /v1/agent/company/runs response.
          required: true
          schema:
            type: string
          name: run_id
          in: path
        - description: >-
            SSE resume cursor (Accept: text/event-stream only). The stream
            replays events with seq greater than this value. It is equivalent to
            the Last-Event-ID header.
          required: false
          schema:
            type: integer
            minimum: 0
          name: starting_after
          in: query
      responses:
        '200':
          description: >-
            Current state of the agent run. With Accept: text/event-stream, the
            response replays and then follows the run as an SSE stream of
            RetrievalAgentStreamEnvelope events. Use starting_after or
            Last-Event-ID to resume. If the stream ends without an agent_result
            event, poll this endpoint with Accept: application/json for the
            terminal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RetrievalAgentStreamEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '403':
          description: The run is not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '404':
          description: Run not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
        - apiKey: []
components:
  schemas:
    CompanyAgentRun:
      properties:
        run_id:
          type: string
          title: Run Id
        object:
          type: string
          const: agent.company.run
          title: Object
          default: agent.company.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/CompanyAgentRunRequest'
            - type: 'null'
      type: object
      required:
        - run_id
        - status
        - created_at
      title: CompanyAgentRun
      description: >-
        The company-agent run resource returned by dispatch (202) and poll
        (GET):

        the retrieval run's shape, with its own object type and the company
        request echoed.
    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: '#/components/schemas/RetrievalAgentResultEvent'
              data_pipeline_answer: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat: '#/components/schemas/HeartbeatEvent'
              reasoning: '#/components/schemas/ReasoningEvent'
              run_summary: '#/components/schemas/RunSummaryEvent'
              status: '#/components/schemas/StatusEvent'
              stream_done: '#/components/schemas/StreamDoneEvent'
              stream_reset: '#/components/schemas/StreamResetEvent'
              subagent: '#/components/schemas/SubagentEvent'
              text: '#/components/schemas/TextEvent'
              tool_call: '#/components/schemas/ToolCallEvent'
              tool_error: '#/components/schemas/ToolErrorEvent'
              tool_result: '#/components/schemas/ToolResultEvent'
              tool_retry: '#/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
    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'.
        refusal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Refusal Code
          description: >-
            Set when Tako rejected the query before the agent ran. Null on
            normal runs. Tako can add new codes, so accept a code you do not
            recognize. The current code is 'rejected_input_classifier'.
        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: the sum of the components
            present.
        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.
        variable_cost:
          anyOf:
            - $ref: '#/components/schemas/UsageVariableCost'
            - type: 'null'
          description: >-
            Variable-cost charge. Present only when the data a request or agent
            run served had a per-unit minimum above its own price: on a search,
            answer or contents request that set variable_cost, and on an agent
            run once it completes.
      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.
    CompanyAgentRunRequest:
      properties:
        query:
          type: string
          title: Query
          description: >-
            Natural-language company or people research request for the company
            agent.
          examples:
            - Directors of publicly traded US banks
        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:
          anyOf:
            - $ref: '#/components/schemas/CompanyAgentEffort'
            - type: 'null'
          description: >-
            Company-research effort tier: low, medium, or high. Omit it on a new
            thread and Tako uses medium; omit it on a follow-up and the run
            keeps the thread's tier.
        source_indexes:
          anyOf:
            - items:
                type: string
                enum:
                  - data
                  - web
              type: array
            - type: 'null'
          title: Source Indexes
          description: >-
            Which sources the agent may use: 'data' (curated knowledge), 'web'
            (open-web search), or both. Omit it on a new thread and the agent
            uses both; omit it on a follow-up and the run keeps the thread's
            sources. 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. True is 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
        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.
          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: CompanyAgentRunRequest
      description: Request body for POST /v1/agent/company/runs.
    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, with one
        exception:

        for up to the durability grace window after a run completes, the GET
        poll can

        report it still running while this frame reports it completed. The poll
        holds

        such a run so the client asks again; this frame is emitted once with
        nothing

        after it, so it cannot. Read the frame as authoritative on status.


        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'
          description: >-
            Tako's relevance label for this card, from the same ladder the flat
            `results` relevance uses. On `effort: deep` an LLM scores cards as
            integers 1 to 5, so a 5 is High and a 4 is Medium. A card the LLM
            leaves unscored keeps its continuous retrieval score and can be High
            below 5. Other efforts score continuously and can label the same
            card higher.
        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: where the data ends
            (coverage_end), the same point as a full date (data_as_of,
            deprecated), and the last refresh date (last_updated). Null when no
            date is available.
        placeholder:
          anyOf:
            - $ref: '#/components/schemas/PlaceholderInfo'
            - type: 'null'
          description: >-
            Set when the card is a placeholder: it carries its title and no data
            points, because the request didn't include its source's data. Null
            on every card that carries its data.
      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 datasets or content items included in the response.
        data_points:
          anyOf:
            - type: integer
            - type: 'null'
          title: Data Points
          description: Number of billed quantitative data points included in the response.
      type: object
      required:
        - cost_usd
        - datasets
      title: UsageData
      description: |-
        The cost and quantity of data delivered in the response.

        `datasets` counts billed datasets or content items. `data_points` counts
        billed quantitative values in generated answer output.
    UsageVariableCost:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of the variable-cost charge.
      type: object
      required:
        - cost_usd
      title: UsageVariableCost
      description: |-
        The variable-cost charge: the per-unit minimum of a variable-cost source
        the response served, above the response's own price.
    CompanyAgentEffort:
      type: string
      enum:
        - low
        - medium
        - high
      title: CompanyAgentEffort
      description: >-
        Effort levels for the company-research agent (POST
        /v1/agent/company/runs).


        All three are available. 'medium' is the default. 'medium' and 'high'
        differ

        in model strength and budget, and 'high' always takes longer.


        'low' is not a smaller 'medium'. It answers from the company registry
        and

        the web only: it screens companies by status, incorporation date,
        registered

        location and industry, and it resolves named companies and people. It
        cannot

        filter or rank by financial metrics such as revenue, market cap or

        headcount, and it cannot screen by SIC code. Ask it for one of those and
        it

        answers the part it can and tells you which part it could not.


        The effort is fixed for the life of a thread. A follow-up that sends a

        different effort gets a 409 response with the code 'effort_mismatch'. To
        use

        a different effort, start a new thread.
    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
    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 inlined rows for the card; 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: they are two prices for the same rows,
            not two charges.
          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. A card export can hold up to 100,000 rows. Don't
            read a large export directly into a model's context: at about 15
            tokens per row, 10,000 rows cost about 150,000 tokens. Write the
            export to a file, on disk or in memory, and have the agent parse it
            with code. Give the model only the rows or results it needs. To cap
            the export instead, set max_rows.
        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'. A card
            export can hold up to 100,000 rows. Don't read a large export
            directly into a model's context: at about 15 tokens per row, 10,000
            rows cost about 150,000 tokens. Write the export to a file, on disk
            or in memory, and have the agent parse it with code. Give the model
            only the rows or results it needs. To cap the export instead, set
            max_rows.
        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'. A card export can hold up to 100,000 rows. Don't
            read a large export directly into a model's context: at about 15
            tokens per row, 10,000 rows cost about 150,000 tokens. Write the
            export to a file, on disk or in memory, and have the agent parse it
            with code. Give the model only the rows or results it needs. To cap
            the export instead, set max_rows.
        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'. Tako truncates the record rows in the
            object to 'max_rows', the same cap every other format takes, and
            bills the rows it returns. A card whose record array is unbounded
            caps that array at the platform export ceiling and reports
            'truncated': true. The payload then also carries the true count for
            its record array. Card types without a card_json shape return 422 on
            /contents and fall back to 'json_compact' on search and answer
            include_contents. A card export can hold up to 100,000 rows. Don't
            read a large export directly into a model's context: at about 15
            tokens per row, 10,000 rows cost about 150,000 tokens. Write the
            export to a file, on disk or in memory, and have the agent parse it
            with code. Give the model only the rows or results it needs. To cap
            the export instead, set max_rows.
        card_data_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Card Data Schema
          description: >-
            JSON Schema for the object in 'card_data'. Read it to learn the
            shape of the payload without parsing the payload. Tako sets this
            whenever content_format is 'card_json'. It is also set in 'url'
            delivery mode and on a Contents quote, where 'card_data' is null and
            the shape is all Tako returns. A search or answer card that you did
            not ask to inline carries a price but no schema. The 'title' field
            and the 'card_type' default inside the schema name the shape. The
            schema describes the payload type, so 'card_data' can omit a field
            the schema declares: Tako drops a measure the provider did not
            supply. Null for every other content_format and for web text.
        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: >-
            Total number of rows in the card's data, independent of how many
            rows were returned. Compare with the rows returned to tell whether a
            larger max_rows returns more. A card that lists a capped slice of a
            larger set, such as the 30 soonest-closing of 330 open
            solicitations, has only that slice as its data, so total_rows is 30
            and total_matching gives the set's size. On an agent run card, it's
            set for a card whose rows are stored with the card, such as a people
            list, and null for other agent run cards. Null for web text.
        total_matching:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Matching
          description: >-
            Size of the whole set behind a card that lists a capped slice of it,
            such as 330 for a card listing the 30 soonest-closing of 330 open
            solicitations. It's the count the card's description states, and
            it's the same on every content format. A larger max_rows doesn't
            return more of that set. Tako reports it for the cards that list
            such a slice: open solicitations, international tenders, a federal
            agency's contracts, and a company's news. Null when the card's rows
            are the whole set, when Tako doesn't count the set (truncated is
            still true), and for web text.
        truncated:
          type: boolean
          title: Truncated
          description: >-
            True when the card has more rows than Tako returned. Tako caps a
            card at the request max_rows or at the card's max_rows_ceiling (at
            most 100,000), and then total_rows is larger than the rows returned.
            It's also true when the card itself lists a capped slice of a larger
            set; then total_matching gives the set's size when Tako counts it.
            An inline /contents export that omits max_rows returns up to 2,000
            rows. On a search or answer response, all cards share a budget of
            2,000 billable rows and a budget of 20,000 inline rows, both spent
            in card order, so a later card can return fewer rows than max_rows
            asked for. A card the billable budget can no longer pay for still
            returns a small preview. A card that arrives after the inline budget
            runs out returns no inline rows, and its export_pricing still prices
            a /contents export of them.
          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, entity, and premium_class. On an agent run
            card, it's set wherever total_rows is. Null for web text and for
            other quotes that carry no tabular columns.
        premium:
          type: boolean
          title: Premium
          description: >-
            True when this item's premium cells are revealed: a /contents
            response to premium=true. False on every search and answer card and
            on a /contents response without the flag. There, a withheld premium
            cell reads [premium: withheld] in CSV and is null in JSON formats,
            and redacted_cells says which rows held a value.
          default: false
        premium_rows:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Premium Rows
          description: >-
            Per premium class ('company_record', 'person_contact'), the number
            of distinct records that the delivered rows hold a value for in a
            column of that class, whether revealed or withheld: one per company
            for 'company_record' and one per person for 'person_contact'. A row
            whose record can't be identified counts as its own record. Multiply
            by export_pricing.premium_row_cpm_usd[class] / 1000 to price the
            premium part of an export before asking for it. A row with cells of
            two classes counts in each. Empty for a card with no premium
            columns; null for web text. On an agent run card, it counts every
            row of the card, so a premium=true export of all total_rows rows
            bills exactly these records when total_rows is within
            max_rows_ceiling. It's set wherever total_rows is.
        redacted_cells:
          anyOf:
            - additionalProperties:
                items:
                  type: integer
                type: array
              type: object
            - type: 'null'
          title: Redacted Cells
          description: >-
            Column header to the 0-based positions, among the delivered rows,
            whose premium value was withheld. Present only when a premium cell
            was withheld; null when premium=true, when nothing was withheld, and
            for web text. Positions index the delivered rows: CSV data rows in
            order, json_records entries, or dataset.rows. In CSV, the same cells
            read [premium: withheld]; a premium cell with no value is blank.
      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-row CPM on every row returned, at the rate that

        ``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard
        Contents

        rate on POST /v1/contents; web text inlined on a search or answer
        response

        is free.


        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 inlined rows for the card, 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).


        On a search or answer WEB result, `cost` is always a prospective

        `/v1/contents` quote and NEVER a charge -- including when Tako inlined
        the

        page text, because inlined web text is free, so the card rule above does
        not

        carry over. That quote arrives on `cost` alone: `export_pricing` is null
        for

        web text, so zeroing `cost` on an inlined result would leave a caller no
        way

        to price a later fetch. A response whose only inlined contents were web
        text

        therefore reports `usage.data` as null -- nothing was billed for data.


        `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 * billed_rows / 1000 + sum over classes c of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is
        the

        SMALLER of the rows the export returns and `max_rows` clamped to

        `max_rows_ceiling`, `premium_rows` is this item's per-class record
        count, and the

        premium term applies only to an export that passes `premium=true`. One

        formula covers every format, card_json included: every export returns no

        more rows than that cap, so a card with fewer rows than the cap bills
        only

        the rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their
        row

        charges are waived, the same waiver a billed inline card's `cost` uses,
        and

        /contents resolves it too. `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, over the rows this response

        inlined, so it is not a `/contents` price for the same card: the two
        cover

        different row counts, because a search response's default inline cap is
        far

        smaller than what `/contents` returns. 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. Read `content_format` to tell a quote from a

        delivery: when it is null, this is just the quote (`cost`); fetch the

        content later via the Contents endpoint.


        Do NOT use "every payload field is null" as that test.
        `card_data_schema`

        is set on a card_json quote and on a card_json `url` delivery, where

        `card_data` is null, so a caller reading absent payloads as "quote"
        reads

        those two as quotes.
    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'
          description: Whether the node is a metric or an entity.
        name:
          type: string
          title: Name
          description: >-
            Display name. Several metrics can share a name when publishers
            report different series, such as two GDP metrics; read `description`
            to tell them apart.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            What the node is. For a metric, what it measures, often with its
            unit and basis. For an entity, a short identification. Absent when
            Tako has none.
      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`. For a node's aliases, resolve the id via
        /v1/graph/node/{id}; for an entity's subtype, use /v1/graph/related.
    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:
        coverage_end:
          anyOf:
            - type: string
            - type: 'null'
          title: Coverage End
          description: >-
            The last data point in the card's data, at the granularity of the
            underlying series. An annual series reports a year (2026). A monthly
            or quarterly series reports a month (2026-06). A daily or intraday
            series reports a full date (2026-06-30). This value can be in the
            future when the card includes projections. Null for card types
            without a coverage date. The value uses ISO 8601 reduced precision,
            so examine the length before you parse it. A date parser reads 2026
            as 2026-01-01, which is the start of the period and not the end. On
            a card with tabs, only the tab this response built is rendered, so
            this date describes THAT tab -- the same card can report a different
            date on a request that opens a different tab. Cache it against the
            response, not against the card id.
          examples:
            - '2026'
            - 2026-06
            - '2026-06-30'
        data_as_of:
          anyOf:
            - type: string
            - type: 'null'
          title: Data As Of
          description: >-
            Deprecated: use coverage_end. The same point, always as a full ISO
            date (YYYY-MM-DD). For a series whose points are periods, this date
            is the period boundary. It is not a day on which Tako observed a
            value.
          deprecated: true
          examples:
            - '2026-10-01'
        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). On a card with tabs this is the ACTIVE tab's refresh
            date, for the same reason coverage_end is tab-scoped: only the tab
            this response built is rendered.
          examples:
            - '2026-07-14'
      type: object
      title: DataFreshness
      description: |-
        When the card's data ends and when Tako last refreshed it. Either field
        may be null when that date is not available for the card type.
    PlaceholderInfo:
      properties:
        withheld_source:
          type: string
          title: Withheld Source
          description: The name of the source whose data the card withholds.
      type: object
      required:
        - withheld_source
      title: PlaceholderInfo
      description: Why a card carries no data points.
    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
        redacted_cells:
          anyOf:
            - additionalProperties:
                items:
                  type: integer
                type: array
              type: object
            - type: 'null'
          title: Redacted Cells
          description: >-
            Column name to the 0-based positions in `rows` whose premium value
            was withheld; those cells are null. Set on a structured-output
            dataset slot when a premium cell was withheld, and null otherwise.
            An inline /contents dataset reports this on the content item
            instead.
      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 delivered. Card-level rate; use this
            value rather than deriving one from the card's sources. It is the
            sum of the rates of the card's separately priced data feeds, or the
            standard rate once for a card with none. Credited producers and
            cited web pages never add to it. This is 0 if your account's row
            charges are waived, in which case an export costs baseline_usd
            whatever its size.
        premium_row_cpm_usd:
          additionalProperties:
            type: number
          type: object
          title: Premium Row Cpm Usd
          description: >-
            USD charged per 1,000 premium records, keyed by premium class
            ('company_record', 'person_contact'), added on top of row_cpm_usd
            when a /contents export passes premium=true. A premium record is a
            distinct company or person that the delivered rows hold a non-null
            value for in a column of that class; the item's premium_rows reports
            the count per class. Empty when the card has no premium columns. Not
            affected by a row-charge waiver.
        free_rows:
          type: integer
          title: Free Rows
          description: >-
            Deprecated and always 0. Row allowances are gone: an account that
            pays nothing per row now reports row_cpm_usd of 0 instead, which the
            cost formula already accounts for. Stop reading this field; it will
            be removed.
          default: 0
          deprecated: true
        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. No format bills more than the
            clamped max_rows, and none bills more rows than it returns. Every
            format obeys this ceiling, including card_json.
        variable_cost_max_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Variable Cost Max Usd
          description: >-
            Set only for a card with data from a source priced per unit: the
            most the source's minimum charge for an export of this card can be.
            An export charges whichever is larger, its own price or that
            minimum, and the quoted cost already accounts for it. The minimum is
            known only after the export, so the actual charge can be lower. The
            export's usage.variable_cost reports a different amount: only what
            the export charged above its own price.
      type: object
      required:
        - baseline_usd
        - row_cpm_usd
        - 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's

        own price = baseline_usd + row_cpm_usd * rows / 1000 + sum over classes
        c of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, rows <=
        max_rows_ceiling, and

        premium_rows[c] the export's premium record count for class c.

        For a card with data from a source priced per unit, the export charges
        the

        larger of its own price and that source's minimum, and

        variable_cost_max_usd is the most that minimum can be.


        row_cpm_usd is the card-level rate and is authoritative: don't derive it

        from the card's listed sources. It is the sum of the rates of the card's

        separately priced data feeds. A card with no separately priced feed
        bills

        the standard rate once, however many sources it lists. An organization
        the

        card credits only as the producer of a redistributed number, and a web
        page

        it cites, never adds to the rate. There is no per-source breakdown. It
        is

        per-CALLER: an account whose row charges are waived sees 0 here, and the

        same formula then yields the baseline alone, which is exactly what that

        account is billed.
    ColumnDescriptor:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: >-
            The column header as exported. This is the CSV header, the
            json_records key, and the dataset column label for this column.
        metric:
          anyOf:
            - type: string
            - type: 'null'
          title: Metric
          description: What the column measures, for example 'Median Sales Price'.
        entity:
          anyOf:
            - type: string
            - type: 'null'
          title: Entity
          description: >-
            What the column is measured FOR: the resolved values of every
            dimension the series is filtered to, joined with an em dash — for
            example 'Austin, TX — Condo'. A card filtered on one dimension
            reports that one value. This field reports resolved display values
            only and never an internal identifier.
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
          description: The unit of every value in the column, for example 'USD'.
        dtype:
          anyOf:
            - $ref: '#/components/schemas/TakoDatasetColumnType'
            - type: 'null'
          description: The data type of the column, inferred from the exported values.
        premium_class:
          anyOf:
            - $ref: '#/components/schemas/PremiumClass'
            - type: 'null'
          description: >-
            Set when the column is premium: 'company_record' or
            'person_contact'. Unless the export passed premium=true, a cell that
            held a value reads [premium: withheld] in CSV and is null in JSON
            formats, so a CSV reader can't parse this column as its dtype; the
            item's redacted_cells says which rows held a value. Null for every
            other column.
      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
      description: >-
        A `metric` is a measurable quantity, such as GDP; an `entity` is what
        one is measured for, such as France.
    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'.
    PremiumClass:
      type: string
      enum:
        - person_contact
        - company_record
      title: PremiumClass
      description: >-
        The price class of a premium column. Person and company records are
        licensed at different per-record rates.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.