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

# List an agent's runs

> Returns a paginated list of the agent's runs, newest first. Transcripts are omitted — fetch a single run to get its transcript.



## OpenAPI

````yaml /openapi.json get /agents/{id}/runs
openapi: 3.1.0
info:
  title: End Close API
  description: REST API is used to interact with the End Close platform.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.endclose.com/v1
security:
  - ApiKeyAuth: []
paths:
  /agents/{id}/runs:
    get:
      summary: List an agent's runs
      description: >-
        Returns a paginated list of the agent's runs, newest first. Transcripts
        are omitted — fetch a single run to get its transcript.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: The unique identifier of the agent
        - in: query
          name: cursor
          required: false
          schema:
            type: string
          description: >-
            Opaque cursor from a previous response's `next_cursor`. Omit for the
            first page.
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: Paginated list of runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentRun'
                  next_cursor:
                    type: string
                    nullable: true
                    description: Opaque cursor for the next page. Null when no more pages.
                  limit:
                    type: integer
        '401':
          description: Unauthorized
        '404':
          description: Agent not found
components:
  schemas:
    AgentRun:
      type: object
      description: >-
        One execution of an agent. Unset fields (e.g. error_message on a
        successful run) are omitted from responses.
      properties:
        id:
          type: string
          format: uuid
        scheduled_agent_id:
          type: string
          format: uuid
          description: The agent this run belongs to
        triggered_by:
          type: string
          enum:
            - manual
            - schedule
            - resume
            - drop
            - api
            - agent
          description: >-
            `api` for runs started through this API with an API key; `agent` for
            runs started by another agent's run using its session key
        triggered_by_user_id:
          type: string
          nullable: true
          description: The user who started a manual run; null for API-triggered runs
        triggered_by_run_id:
          type: string
          nullable: true
          description: 'For agent-triggered runs: the run whose agent started this one'
        agent_review_task_id:
          type: string
          nullable: true
          description: 'For resume runs: the review task whose resolution this run executes'
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        duration_ms:
          type: integer
          nullable: true
        error_message:
          type: string
          nullable: true
        summary:
          type: string
          nullable: true
          description: The agent's markdown summary of what it did
        model:
          type: string
          nullable: true
          description: The model this run executed on
        total_input_tokens:
          type: integer
          nullable: true
        total_output_tokens:
          type: integer
          nullable: true
        output_files:
          type: array
          items:
            $ref: '#/components/schemas/AgentFile'
          description: Files the agent produced for the operator
        dropped_files:
          type: array
          items:
            $ref: '#/components/schemas/AgentFile'
          description: 'For drop runs: the file(s) this run was triggered to process'
        delivery:
          type: object
          nullable: true
          description: >-
            The email delivery record for this run's output files, when delivery
            ran
        transcript:
          type: array
          items:
            type: object
          description: Full event transcript. Only included when fetching a single run
        created_at:
          type: string
          format: date-time
    AgentFile:
      type: object
      description: >-
        A file attached to an agent (input) or produced by a run (output). `url`
        is a signed, relative download path on the API host.
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        byte_size:
          type: integer
        content_type:
          type: string
        created_at:
          type: string
          format: date-time
        url:
          type: string
          description: Signed download path, relative to the API host
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````