> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.kolena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agent Runs

> Return all Runs for an Agent, including results

export const limit_0 = 1200

<Info>
  **Rate Limit:** This endpoint is limited to **{limit_0.toLocaleString()} requests per minute** per user.
</Info>


## OpenAPI

````yaml openapi.json GET /api/v1/client/agents/{agent_id}/runs
openapi: 3.1.0
info:
  title: kolena
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/client/agents/{agent_id}/runs:
    get:
      tags:
        - client
        - agents
      summary: Client List Agent Runs
      operationId: client_list_agent_runs_api_v1_client_agents__agent_id__runs_get
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: integer
            title: Agent Id
        - name: page_number
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Optionally specify the index of the Runs page to fetch.
            default: 0
            title: Page Number
          description: Optionally specify the index of the Runs page to fetch.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 0
            description: Optionally specify the maximum number of Runs to fetch.
            default: 50
            title: Page Size
          description: Optionally specify the maximum number of Runs to fetch.
        - name: run_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: integer
                type: array
              - type: 'null'
            description: Optionally specify specific Run IDs to fetch.
            title: Run Ids
          description: Optionally specify specific Run IDs to fetch.
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/AgentRunStatus'
              - type: 'null'
            description: >-
              Optionally filter by the `status` of Runs, e.g. `running` or
              `success`.
            title: Status
          description: >-
            Optionally filter by the `status` of Runs, e.g. `running` or
            `success`.
        - name: user_defined_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Optionally filter by `user_defined_id`s of Runs.
            title: User Defined Ids
          description: Optionally filter by `user_defined_id`s of Runs.
        - name: created_gte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: >-
              Optionally filter Runs created on or after this timestamp
              (inclusive). Accepts ISO 8601 format (e.g., `2024-01-15T10:30:00Z`
              or `2024-01-15T10:30:00+00:00`).
            title: Created Gte
          description: >-
            Optionally filter Runs created on or after this timestamp
            (inclusive). Accepts ISO 8601 format (e.g., `2024-01-15T10:30:00Z`
            or `2024-01-15T10:30:00+00:00`).
        - name: created_lte
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: >-
              Optionally filter Runs created on or before this timestamp
              (inclusive). Accepts ISO 8601 format (e.g., `2024-01-15T23:59:59Z`
              or `2024-01-15T23:59:59+00:00`).
            title: Created Lte
          description: >-
            Optionally filter Runs created on or before this timestamp
            (inclusive). Accepts ISO 8601 format (e.g., `2024-01-15T23:59:59Z`
            or `2024-01-15T23:59:59+00:00`).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentRunsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    AgentRunStatus:
      type: string
      enum:
        - running
        - success
        - failed
      title: AgentRunStatus
    ListAgentRunsResponse:
      properties:
        runs:
          items:
            $ref: '#/components/schemas/AgentRun'
          type: array
          title: Runs
          description: The fetched page of Runs from this Agent.
        total_pages:
          type: integer
          title: Total Pages
          description: >-
            The total number of pages of Runs. Use the request arguments
            `page_number` and `page_size` to control which Runs are fetched.
        page_number:
          type: integer
          title: Page Number
          description: The number of the fetched page.
        page_size:
          type: integer
          title: Page Size
          description: The page size, i.e. number of Runs, fetched.
      type: object
      required:
        - runs
        - total_pages
        - page_number
        - page_size
      title: ListAgentRunsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentRun:
      properties:
        agent_id:
          type: integer
          title: Agent Id
          description: The ID of the Agent being run.
        run_id:
          type: integer
          title: Run Id
          description: The ID of this Agent Run.
        user_defined_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Defined Id
          description: An optional user-defined ID attached to this Run.
        created:
          type: string
          format: date-time
          title: Created
          description: >-
            When this Run was created, formatted as an ISO 8601 timestamp (e.g.
            `2025-12-31T10:15:45+00:00`)
        updated:
          type: string
          format: date-time
          title: Updated
          description: >-
            When this Run was last updated, formatted as an ISO 8601 timestamp
            (e.g. `2025-12-31T10:15:45+00:00`)
        completed:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed
          description: >-
            When all Prompts in this Run completed, formatted as an ISO 8601
            timestamp (e.g. `2025-12-31T10:15:45+00:00`).


            The time between `created` and `completed` is the total time taken
            by the Agent for this Run. Will be `null` if the Run is still in
            progress and for historical Runs created before March 2026.
        files:
          items:
            type: string
          type: array
          title: Files
          description: List of filenames included in this Run.
        run_url:
          type: string
          title: Run Url
          description: Link to this Run on [agents.kolena.com](https://agents.kolena.com/).
        order:
          items:
            type: string
          type: array
          title: Order
          description: >-
            The order of Prompts in this Agent. When results are ready for a
            Prompt, it will be included in the `data` object.
        data:
          additionalProperties:
            $ref: '#/components/schemas/AgentRunResult'
          type: object
          title: Data
          description: >-
            The output data from completed Prompts, keyed on Prompt name.


            Once a Prompt is completed (status `success` or `failed`), it will
            be included in this object. Any `running` prompts are omitted.
        status:
          $ref: '#/components/schemas/AgentRunStatus'
          description: The status of this Run.
        usage:
          anyOf:
            - $ref: '#/components/schemas/AgentCreditUsage'
            - type: 'null'
          description: >-
            For organizations with credit-based billing enabled, report the
            total credits used for this Run. `null` for organizations using
            page-based billing.
      type: object
      required:
        - agent_id
        - run_id
        - user_defined_id
        - created
        - updated
        - completed
        - files
        - run_url
        - order
        - data
        - status
      title: AgentRun
      examples:
        - agent_id: 1
          completed: '2025-01-01T12:02:00'
          created: '2025-01-01T12:00:00'
          data:
            Another Example:
              end_time: '2025-01-05T03:13:59.000013'
              metadata:
                citations:
                  - file: demo2.csv
                confidence: 0.9
                reasoning: The order amount is listed in demo2.csv
                url_citations: []
              start_time: '2025-01-05T03:13:45.000051'
              status: success
              usage:
                credits_used: 0.071
              value: 123
            Example Prompt:
              end_time: '2025-01-05T03:05:10.000102'
              metadata:
                citations:
                  - file: demo1.pdf
                    pages:
                      - 2
                      - 5
                    regions:
                      - page: 2
                        point:
                          - 20
                          - 15
                        text: Account number
                confidence: 1
                reasoning: Looking at file demo1.pdf, ...
                url_citations:
                  - cited_text: Example text from website
                    title: Kolena Example
                    url: https://example.com/kolena
              start_time: '2025-01-05T03:05:05.000057'
              status: success
              usage:
                credits_used: 0.052
              value: foo
          files:
            - demo1.pdf
            - demo2.csv
          order:
            - Example Prompt
            - Another Example
          run_id: 1
          run_url: https://agents.kolena.com/my_org/agents/1/runs/1
          status: success
          updated: '2025-01-05T00:00:00'
          usage:
            credits_used: 0.123
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentRunResult:
      properties:
        status:
          $ref: '#/components/schemas/AgentRunStatus'
          description: >-
            The status of this Prompt, either `success` or `failed`. Prompts
            that are `running` are omitted from the `data` object.
        value:
          title: AnyValue
          description: The output value from this Prompt on this Run.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: An error string if the Prompt failed to execute, otherwise `null`.
        metadata:
          anyOf:
            - $ref: '#/components/schemas/AgentRunResultMetadata'
            - type: 'null'
          description: >-
            Metadata associated with this Prompt run, including reasoning,
            citations, and confidence values.
        user_input:
          anyOf:
            - $ref: '#/components/schemas/CellResultUserInput'
            - type: 'null'
          description: Optional user-provided correction to this Prompt output.
        start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Start Time
          description: ISO 8601 timestamp indicating when this Prompt started running.
        end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Time
          description: ISO 8601 timestamp indicated when this Prompt completed.
        usage:
          anyOf:
            - $ref: '#/components/schemas/AgentCreditUsage'
            - type: 'null'
          description: Usage information for this Prompt.
      type: object
      required:
        - status
        - value
        - error
        - metadata
      title: AgentRunResult
    AgentCreditUsage:
      properties:
        credits_used:
          type: number
          title: Credits Used
          description: The credits used by this object.
      type: object
      required:
        - credits_used
      title: AgentCreditUsage
    AgentRunResultMetadata:
      properties:
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
          description: Reasoning behind the `value` provided as a Prompt output.
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
          description: >-

            A confidence value on `[0, 1]` indicating uncertainty around the
            provided `value`. A confidence of 1 indicates that the model is
            highly certain of the result.
        citations:
          items:
            $ref: '#/components/schemas/AgentRunResultMetadataCitation'
          type: array
          title: Citations
          description: >-
            A list of citations, including documents and page numbers, used to
            produce the output `value`.
        url_citations:
          items:
            $ref: '#/components/schemas/AgentRunResultMetadataUrlCitation'
          type: array
          title: Url Citations
          description: >-
            A list of URL citations, including web pages and resources, used to
            produce the output `value`.
      type: object
      required:
        - reasoning
        - confidence
        - citations
      title: AgentRunResultMetadata
    CellResultUserInput:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/CellResultUserData'
            - type: 'null'
        data_updated:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Data Updated
        data_edited_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Data Edited By
      type: object
      title: CellResultUserInput
    AgentRunResultMetadataCitation:
      properties:
        file:
          type: string
          title: File
          description: The name of the file being referenced.
        pages:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Pages
          description: >-
            The relevant page(s) referenced by the model, or `null` if
            referencing a non-paginated file type.
        regions:
          anyOf:
            - items:
                $ref: '#/components/schemas/CitationRegion'
              type: array
            - type: 'null'
          title: Regions
          description: The regions of interest supporting the citations.
      type: object
      required:
        - file
        - pages
      title: AgentRunResultMetadataCitation
    AgentRunResultMetadataUrlCitation:
      properties:
        url:
          type: string
          title: Url
          description: The URL being referenced.
        title:
          type: string
          title: Title
          description: The title of the web page or resource.
        cited_text:
          type: string
          title: Cited Text
          description: The specific text from the URL that was cited.
      type: object
      required:
        - url
        - title
        - cited_text
      title: AgentRunResultMetadataUrlCitation
    CellResultUserData:
      properties:
        value:
          title: AnyValue
      type: object
      title: CellResultUserData
    CitationRegion:
      properties:
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
          description: The page where this supporting evidence appears.
        point:
          anyOf:
            - prefixItems:
                - type: integer
                - type: integer
              type: array
              maxItems: 2
              minItems: 2
            - type: 'null'
          title: Point
          description: >-
            The approximate position of the evidence on the page. [x, y]
            coordinates as percentages (0-100), where [0, 0] is the top-left and
            [100, 100] is the bottom-right.
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: A short excerpt or label of the supporting evidence.
      type: object
      required:
        - page
        - point
        - text
      title: CitationRegion
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`. The `<token>`
        represents your API key, which must be acquired from the Kolena
        platform.

````