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

# List an automation's runs

> Newest first. Every run is here however it was started: from the app, a schedule, a webhook, an email, or this API.



## OpenAPI

````yaml /openapi.json get /api/automations/{automationId}/runs
openapi: 3.1.0
info:
  title: Workspace API
  version: 1.0.0
  description: >-
    Every workspace answers these endpoints. Nothing is registered and nothing
    is switched on: an automation that appears in your Automations tab is
    already readable here.


    The base URL is your workspace's own. Ask the agent for it, or find it under
    Settings → API on the workspace. It is stable and never changes.


    Every call carries your workspace's API key, as `Authorization: Bearer
    <key>` or in the `x-desert-api-key` header. The key is on the same settings
    page as the URL, and generating a new one there revokes the old one
    immediately.
servers:
  - url: https://www.rundesert.com/p/{workspaceId}
    description: Your workspace's public API
    variables:
      workspaceId:
        default: px_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
        description: >-
          The id in your workspace's public URL. It is the address, not the
          credential — the API key is what authorises the call.
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Automations
    description: What this workspace can do.
  - name: Runs
    description: What it has done, and what came out.
  - name: Files
    description: Downloading what an automation produced.
  - name: Custom endpoints
    description: Anything else your agent wrote.
paths:
  /api/automations/{automationId}/runs:
    get:
      tags:
        - Runs
      summary: List an automation's runs
      description: >-
        Newest first. Every run is here however it was started: from the app, a
        schedule, a webhook, an email, or this API.
      operationId: listRuns
      parameters:
        - $ref: '#/components/parameters/AutomationId'
        - name: limit
          in: query
          description: >-
            How many runs to return. Clamped to 100, so asking for more is not
            an error, it just returns 100.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: A page of runs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunPage'
              example:
                automation: invoice-extract
                limit: 2
                runs:
                  - runId: 1786945498854-80788d
                    status: done
                    source: manual
                    startedAt: '2026-08-17T05:44:58.854Z'
                    endedAt: '2026-08-17T05:45:09.132Z'
                    duration: 10277
                    steps: 1
                    error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    AutomationId:
      name: automationId
      in: path
      required: true
      description: The automation's id, as returned by `GET /api/automations`.
      schema:
        type: string
      example: invoice-extract
  schemas:
    RunPage:
      type: object
      properties:
        automation:
          type: string
        limit:
          type: integer
          description: The limit actually applied, after clamping.
        runs:
          type: array
          items:
            $ref: '#/components/schemas/Run'
    Run:
      type: object
      properties:
        runId:
          type: string
        automation:
          type: string
        status:
          $ref: '#/components/schemas/RunStatus'
        source:
          type: string
          description: 'What started it: `manual`, `schedule`, `webhook`, `email`.'
        startedAt:
          type: string
          format: date-time
        endedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Null while it is still going.
        duration:
          type:
            - integer
            - 'null'
          description: Milliseconds. Null while it is still going.
        steps:
          type: integer
          description: How many progress steps it reported.
        error:
          type:
            - string
            - 'null'
    Error:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
    RunStatus:
      type: string
      enum:
        - running
        - done
        - error
      description: >-
        `running` means it has not finished. `error` means it finished badly,
        and `error` on the run says why.
  responses:
    Unauthorized:
      description: >-
        The API key was missing or wrong. Check Settings → API for the current
        one — generating a new key there stops the old one working immediately.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
    NotFound:
      description: No such automation, or no such run under it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: No such automation
    RateLimited:
      description: >-
        600 requests a minute across the whole workspace, shared with anyone
        loading its pages. Wait and try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate limited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your workspace's API key, from Settings → API. Sent as `Authorization:
        Bearer dk_...`.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-desert-api-key
      description: >-
        The same key, for callers whose `Authorization` header is already spoken
        for by their own auth. Send one form or the other, not both.

````