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

# List runs

> Retrieves a filtered list of workflow execution runs. This endpoint provides:
- Time-based filtering with custom start/end timestamps
- Filtering by workflow, execution status, or vault credential
- Configurable result limits up to 10,000 runs
- Results sorted by creation time (newest first)
- Cursor-based pagination for large result sets

**Pagination:** For large queries (above 500 runs), we recommend using cursor-based pagination. Set `limit` to 500 and fetch pages sequentially by passing the `created_at` value of the last returned row as the `cursor` parameter for the next request. When the response contains fewer rows than the requested limit, there are no more pages.



## OpenAPI

````yaml run-api/run-api.yaml get /runs
openapi: 3.1.0
info:
  title: CloudCruise Run API
  version: 0.1.0
  description: >-
    Endpoints for managing workflow executions, user interactions, and
    retrieving execution results.
servers:
  - url: https://api.cloudcruise.com
    description: CloudCruise Platform Production API Server
security:
  - AuthScheme: []
paths:
  /runs:
    get:
      summary: List runs
      description: >-
        Retrieves a filtered list of workflow execution runs. This endpoint
        provides:

        - Time-based filtering with custom start/end timestamps

        - Filtering by workflow, execution status, or vault credential

        - Configurable result limits up to 10,000 runs

        - Results sorted by creation time (newest first)

        - Cursor-based pagination for large result sets


        **Pagination:** For large queries (above 500 runs), we recommend using
        cursor-based pagination. Set `limit` to 500 and fetch pages sequentially
        by passing the `created_at` value of the last returned row as the
        `cursor` parameter for the next request. When the response contains
        fewer rows than the requested limit, there are no more pages.
      operationId: list_runs
      parameters:
        - name: start_time
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              ISO 8601 timestamp for the earliest run creation time to include.

              Cannot be older than 1 year. Defaults to 24 hours ago if not
              provided.
            example: '2026-02-14T00:00:00Z'
        - name: end_time
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: >-
              ISO 8601 timestamp for the latest run creation time to include.

              Must be greater than or equal to start_time and cannot be in the
              future.
            example: '2026-02-15T23:59:59Z'
        - name: workflow_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            description: Filter runs by workflow ID
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - execution.queued
              - execution.start
              - execution.failed
              - execution.success
              - execution.paused
              - execution.stopped
              - execution.requeued
            description: Filter runs by execution status
        - name: credential_id
          in: query
          required: false
          schema:
            type: string
            description: Filter runs by vault credential (permissioned_user_id)
        - name: workflow_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
            description: Filter runs by multiple workflow IDs
        - name: credential_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: >-
              Filter runs by multiple vault credential IDs
              (permissioned_user_id)
        - name: statuses
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - execution.queued
                - execution.start
                - execution.failed
                - execution.success
                - execution.paused
                - execution.stopped
                - execution.requeued
            description: Filter runs by multiple execution statuses
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
            description: Maximum number of runs to retrieve
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: |-
              ISO 8601 timestamp for cursor-based pagination. Returns only runs
              with created_at strictly before this timestamp. Use the created_at
              value of the last row from the previous page as the cursor for the
              next request. When the number of returned rows is less than the
              requested limit, there are no more pages.
            example: '2026-02-15T10:00:00Z'
      responses:
        '200':
          description: Filtered runs successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FilteredRun'
        '400':
          description: Invalid request parameters
components:
  schemas:
    FilteredRun:
      type: object
      description: Summary of a workflow execution run
      properties:
        session_id:
          type: string
          format: uuid
          example: e5f6a7b8-9abc-4def-0123-56789abcdef0
          description: Unique identifier for the run session
        created_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-02-15T10:00:00Z'
          description: When the run was created
        workflow_id:
          type: string
          format: uuid
          nullable: true
          example: d4e5f6a7-89ab-45cd-ef01-456789012abc
          description: Identifier for the workflow that was executed
        workspace_id:
          type: string
          format: uuid
          nullable: true
          example: 1a2b3c4d-5e6f-4789-a012-bcdef0123456
          description: Identifier for the workspace the run belongs to
        status:
          type: string
          enum:
            - execution.queued
            - execution.start
            - execution.failed
            - execution.success
            - execution.paused
            - execution.stopped
            - execution.requeued
          example: execution.success
          description: Current execution status of the run
        execution_start:
          type: string
          format: date-time
          nullable: true
          example: '2026-02-15T10:00:01Z'
          description: When execution began
        execution_end:
          type: string
          format: date-time
          nullable: true
          example: '2026-02-15T10:00:30Z'
          description: When execution completed
        dry_run:
          type: boolean
          nullable: true
          example: false
          description: Whether this was a dry run
      required:
        - session_id
        - status
  securitySchemes:
    AuthScheme:
      type: apiKey
      name: cc-key
      in: header
      description: >-
        API key-based authentication. Provide your CloudCruise API key in the
        cc-key header.

````