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

> Retrieve the current state and result of an agent run

## Notes

* Poll with the `run_id` returned by [Dispatch a run](/api-reference/agent-dispatch). `status` progresses `queued` → `running` → `completed` / `failed`; the `result` is populated once `status` is `completed`.
* 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. See the [Agent guide](/documentation/integrating-tako/guides/agent).


## OpenAPI

````yaml GET /v1/agent/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/runs/{run_id}:
    get:
      tags:
        - agent
      summary: Poll an agent run
      description: >-
        Retrieve the current state of an agent run. Poll until status is
        'completed' or 'failed'. result is populated when status is 'completed'.
      operationId: getAgentRun
      parameters:
        - description: Run ID returned by POST /v1/agent/runs
          required: true
          schema:
            type: string
          name: run_id
          in: path
        - description: >-
            SSE resume cursor (Accept: text/event-stream only). Replay events
            with seq strictly greater than this value. 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,
            resumes/tails the run as an SSE stream of AgentStreamEnvelope 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 terminal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentStreamEnvelope'
        '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:
    AgentRun:
      properties:
        run_id:
          type: string
          title: Run Id
        object:
          type: string
          const: agent.run
          title: Object
          default: agent.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/AgentResult'
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
      type: object
      required:
        - run_id
        - status
        - created_at
      title: AgentRun
      description: The run resource returned by dispatch (202) and poll (GET).
    AgentStreamEnvelope:
      properties:
        seq:
          type: integer
          minimum: 0
          title: Seq
          description: >-
            Monotonic event sequence number; use as the resume cursor. Values
            are NOT contiguous — the public stream filters internal block kinds,
            so gaps are expected and do not mean events were lost.
        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/AgentResultEvent'
            - $ref: '#/components/schemas/HeartbeatEvent'
            - $ref: '#/components/schemas/StreamResetEvent'
            - $ref: '#/components/schemas/StreamDoneEvent'
          title: Block
          discriminator:
            propertyName: kind
            mapping:
              agent_result:
                $ref: '#/components/schemas/AgentResultEvent'
              data_pipeline_answer:
                $ref: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat:
                $ref: '#/components/schemas/HeartbeatEvent'
              reasoning:
                $ref: '#/components/schemas/ReasoningEvent'
              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: AgentStreamEnvelope
      description: >-
        Public SSE envelope for the Agent run stream. `run_id` is the run/task
        id

        (renamed from the native envelope's `task_id` for resource consistency).


        `seq` is monotonically increasing but NOT contiguous: the public stream
        omits

        internal block kinds, so gaps in `seq` are expected and do not indicate
        lost

        events. Use `seq` only as the resume cursor (`starting_after` /
        `Last-Event-ID`),

        not as a completeness check.
    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
    AgentResult:
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        web_results:
          items:
            $ref: '#/components/schemas/WebResult'
          type: array
          title: Web Results
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
      type: object
      title: AgentResult
      description: >-
        Final agent output. answer is markdown; cards reuse the sibling
        TakoCard.
    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 chart(s) for the answer. Carries

        only chart references; the answer text streams in `text` events and the

        structured result arrives in the terminal `agent_result` event, not
        here.
    AgentResultEvent:
      properties:
        kind:
          type: string
          const: agent_result
          title: Kind
          default: agent_result
        id:
          type: string
          title: Id
        data:
          $ref: '#/components/schemas/AgentResult'
      type: object
      required:
        - id
        - data
      title: AgentResultEvent
    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/KnowledgeCardSource'
              type: array
            - type: 'null'
          title: Sources
        methodologies:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardMethodology'
              type: array
            - type: 'null'
          title: Methodologies
        source_indexes:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/CardSourceIndex'
                  - $ref: '#/components/schemas/CardSourceIndexSegment'
              type: array
            - type: 'null'
          title: Source Indexes
        card_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Type
        relevance:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeCardRelevance'
            - type: 'null'
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Relevance Score
          description: >-
            Numeric relevance of this card to the query on a 1.0-5.0 scale (5.0
            = exact match; higher is more relevant). Only populated for entitled
            accounts; null otherwise.
      type: object
      title: TakoCard
      description: >-
        A Tako knowledge card on the new search/answer surface. Mirrors the

        legacy KnowledgeCard minus data_url / visualization_data /
        ideal_viz_decisions,

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

        Distinct from `KnowledgeCardSource` (a citation inside a synthesized
        answer) and `KnowledgeCard` (a Tako visualization). Web results are
        raw retrieval output — title, URL, optional snippet — independent of
        any LLM synthesis that may also happen over them.
    KnowledgeCardSource:
      properties:
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
          description: The name of the source
          examples:
            - S&P Global
            - The World Bank
        source_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Description
          description: The description of the source
          examples:
            - >-
              S&P Global is a US-based financial data and analytics company that
              provides products and services to the financial industry.
            - >-
              The World Bank is an international financial institution that
              provides financial and technical assistance to developing
              countries to help them achieve sustainable economic growth and
              improve living conditions.
        source_index:
          anyOf:
            - $ref: '#/components/schemas/CardSourceIndex'
            - $ref: '#/components/schemas/CardSourceIndexSegment'
            - $ref: '#/components/schemas/CardSourcePrivateIndex'
          title: Source Index
          description: The index of the source
          examples:
            - tako
            - web
            - connected_data
            - index_type: connected_data
              segment_id: '123'
            - index_type: connected_data
              private_index_id: '123'
              segment_id: '123'
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL of the source
          examples:
            - https://xignite.com
            - https://stats.com
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
          description: >-
            Raw excerpt(s) retrieved from the source page — the unmodified web
            content the answer was grounded in, NOT the synthesized answer.
            Populated for WEB sources; null for sources that don't carry an
            extracted excerpt (e.g. TAKO sources).
          examples:
            - >-
              Domestic (28.1%) $154,061,981 | International (71.9%) $394,144,531
              | Worldwide $548,206,512. Release Date Nov 7, 2025. Distributor
              20th Century Studios.
      type: object
      required:
        - source_name
        - source_description
        - source_index
        - url
      title: KnowledgeCardSource
    KnowledgeCardMethodology:
      properties:
        methodology_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Name
          description: The name of the methodology
          examples:
            - Where the Data Comes From - S&P Global
        methodology_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Description
          description: The description of the methodology
          examples:
            - >-
              The financial metrics are collected from S&P Global, where
              information is sourced from original regulatory filings, press
              releases, and subsequent restatements. Data points, including over
              5,000 financial, supplemental, segment, ratio, and
              industry-specific items, are standardized across over 180,000
              companies to ensure consistency and comparability across different
              reporting formats. This comprehensive and methodical process
              enables robust historical analysis and back-testing by seamlessly
              integrating diverse financial datasets while preserving the
              granularity of the original reports.
      type: object
      required:
        - methodology_name
        - methodology_description
      title: KnowledgeCardMethodology
    CardSourceIndex:
      type: string
      enum:
        - tako
        - web
        - connected_data
        - tako_deep_v2
      title: CardSourceIndex
    CardSourceIndexSegment:
      properties:
        index_type:
          $ref: '#/components/schemas/CardSourceIndex'
        segment_id:
          type: string
          title: Segment Id
          description: An ID for a segment of a source index
          examples:
            - '123'
      type: object
      required:
        - index_type
        - segment_id
      title: CardSourceIndexSegment
      description: >-
        A segment of a source index. Within a source index, a segment is a
        subset of the data.

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

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

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

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

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

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

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

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

````