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

# List Runs

> Retrieves a paginated list of workflow runs for the specified webhook. Runs are sorted by creation time in descending order (newest first).

**Rate Limit:** 120 requests per minute per API key.



## OpenAPI

````yaml GET /{key}/runs
openapi: 3.1.0
info:
  title: Cordage Webhook API
  description: >-
    The Cordage Webhook API allows you to programmatically trigger workflows,
    monitor run status, and retrieve outputs. Use webhooks to integrate your AI
    workflows into external applications, automation pipelines, or custom tools.
  version: 1.0.0
  contact:
    name: Cordage Support
    url: https://trycordage.com
servers:
  - url: https://api.trycordage.com/api/webhooks
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Workflows
    description: Trigger and manage workflow executions
  - name: Runs
    description: Monitor and control workflow runs
paths:
  /{key}/runs:
    get:
      tags:
        - Runs
      summary: List runs
      description: >-
        Retrieves a paginated list of workflow runs for the specified webhook.
        Runs are sorted by creation time in descending order (newest first).


        **Rate Limit:** 120 requests per minute per API key.
      operationId: listRuns
      parameters:
        - name: key
          in: path
          description: The webhook key
          required: true
          schema:
            type: string
            example: wh_abc123xyz
        - name: limit
          in: query
          description: Maximum number of runs to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: Number of runs to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: List of runs retrieved successfully
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per window
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 119
            X-RateLimit-Reset:
              description: Seconds until rate limit resets
              schema:
                type: integer
                example: 45
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRunsResponse'
              example:
                runs:
                  - run_id: 550e8400-e29b-41d4-a716-446655440000
                    status: completed
                    created_at: '2024-01-15T10:30:00Z'
                    completed_at: '2024-01-15T10:32:15Z'
                  - run_id: 660e8400-e29b-41d4-a716-446655440001
                    status: running
                    created_at: '2024-01-15T10:25:00Z'
                    completed_at: null
                total: 2
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - API key doesn't have access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListRunsResponse:
      type: object
      required:
        - runs
        - total
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/RunSummary'
          description: List of workflow runs
        total:
          type: integer
          minimum: 0
          description: Total number of runs returned
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
        retry_after:
          type: integer
          description: Seconds to wait before retrying (only present for rate limit errors)
    RunSummary:
      type: object
      required:
        - run_id
        - status
        - created_at
      properties:
        run_id:
          type: string
          format: uuid
          description: Unique identifier for this workflow run
        status:
          $ref: '#/components/schemas/RunStatus'
        created_at:
          type: string
          format: date-time
          description: When the run was started
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: When the run completed (null if still running)
    RunStatus:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled
      description: The current status of a workflow run
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        API key authentication. Get your API key from the workspace settings.

        Example: `Authorization: Bearer cordage_xxxxxxxxxxxx`

````