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

# List Retrieval Agent runs

> List the caller's Retrieval Agent runs, newest first

## Notes

* Returns the authenticated caller's Retrieval Agent runs, newest first, as a list envelope: `{ "object": "list", "data": [ … ], "has_more": bool, "next_cursor": string | null }`.
* Each item is a trimmed `RetrievalAgentRunSummary` (`run_id`, `status`, `created_at`, `completed_at`, `thread_id`, `usage`) — fetch full detail via [Poll a Retrieval Agent run](/api-reference/agent-retrieval-poll).
* Paginate with `cursor` (a prior response's `next_cursor`) and `limit` (default 20, max 100).


## OpenAPI

````yaml GET /v1/agent/retrieval/runs
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/agent/retrieval/runs:
    get:
      tags:
        - agent
      summary: List retrieval agent runs
      description: >-
        List the authenticated caller's retrieval agent runs, newest first.
        Returns trimmed run summaries. Fetch full detail via GET
        /v1/agent/retrieval/runs/{run_id}.
      operationId: listRetrievalAgentRuns
      parameters:
        - description: Opaque pagination cursor from a previous response's next_cursor.
          required: false
          schema:
            type: string
          name: cursor
          in: query
        - description: Max runs to return (default 20, max 100).
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
          name: limit
          in: query
      responses:
        '200':
          description: A page of the caller's retrieval agent runs, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalAgentRunList'
        '400':
          description: Invalid pagination parameter (limit or cursor).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
        - apiKey: []
components:
  schemas:
    RetrievalAgentRunList:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/RetrievalAgentRunSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - data
      title: RetrievalAgentRunList
      description: |-
        List envelope for GET /v1/agent/retrieval/runs. The shape follows the
        OpenAI and Exa list convention.
    ErrorObject:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ErrorObject
    RetrievalAgentRunSummary:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        object:
          type: string
          const: agent.retrieval.run
          title: Object
          default: agent.retrieval.run
      type: object
      required:
        - run_id
        - status
        - created_at
      title: RetrievalAgentRunSummary
    AgentRunStatus:
      type: string
      enum:
        - queued
        - running
        - completed
        - failed
      title: AgentRunStatus
    Usage:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: >-
            Total quoted USD cost of this request. Sum of compute cost and data
            cost.
        compute:
          anyOf:
            - $ref: '#/components/schemas/UsageCompute'
            - type: 'null'
          description: >-
            Compute cost breakdown. Present only on surfaces with a compute step
            (absent for contents).
        data:
          anyOf:
            - $ref: '#/components/schemas/UsageData'
            - type: 'null'
          description: >-
            Inline-data cost breakdown. Present only when the surface emitted
            billable inline data.
      type: object
      required:
        - total_cost_usd
      title: Usage
      description: |-
        Usage for one metered request. `total_cost_usd` is always present (the
        total quoted charge). `compute` and `data` are the additive breakdown;
        each appears only where it applies. total_cost_usd always equals the sum
        of the components that appear.
    UsageCompute:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of running the operation.
      type: object
      required:
        - cost_usd
      title: UsageCompute
      description: |-
        The cost of running the operation. Absent on surfaces with no compute
        step (contents).
    UsageData:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of the inline data delivered in the response.
        datasets:
          type: integer
          title: Datasets
          description: Number of billed data units (datasets) included in the response.
      type: object
      required:
        - cost_usd
        - datasets
      title: UsageData
      description: |-
        The cost and quantity of inline data delivered in the response: the
        agent per-dataset surcharge, the search and answer include_contents
        charge, or the contents per-item cost. `datasets` is the count of billed
        data units. Absent when the surface did not or cannot emit inline data
        (for example, the answer agent).
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````