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

# List Workflow Runs

> Read paginated workflow runs with node inputs, outputs, errors, and logs

Returns paginated runs and node executions for a workflow the API key user can edit. Use this path when you need filters such as test versus production, or a cursor. Flattened export with a required date range is a different contract on [Workflow Run Export](/en/developer/workflow-api/intro-to-workflow-api).

## Base URL

```
https://api.langdock.com/workflows/v1/runs
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Required scopes

This endpoint requires the `WORKFLOW_API` scope (**Workflow Read API**) and editor access.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `workflowId` | string | Yes | UUID of the workflow. |
| `limit` | integer | No | Number of runs to return. Default: `50`. Maximum: `100`. |
| `cursor` | string | No | Run UUID from `nextCursor` in the previous response. |
| `runId` | string | No | Filter to a single run UUID. |
| `runMode` | string | No | `test` or `production`. Must agree with `version` when both are set: `test` with `0`, production with a published version. |
| `status` | string | No | Run status: `PENDING`, `IN_PROGRESS`, `AWAITING_INPUT`, `COMPLETED`, `FAILED`, or `CANCELLED`. |
| `from` | string | No | Start of the run creation range. ISO 8601 timestamp or `YYYY-MM-DD`. Must be sent together with `to`. A date-only value starts at `00:00:00.000` UTC. |
| `to` | string | No | End of the run creation range. Must be equal to or later than `from`. A date-only value ends at `23:59:59.999` UTC. |
| `version` | string | No | Workflow version used for the run. Version `0` is the draft used for test runs. |

Unavailable action or agent data is redacted. Execution payloads follow the workflow API payload limit.

## Example

```javascript theme={null}
const axios = require("axios");

async function listWorkflowRuns(workflowId) {
  const response = await axios.get(
    "https://api.langdock.com/workflows/v1/runs",
    {
      params: {
        workflowId,
        runMode: "production",
        limit: 50
      },
      headers: {
        Authorization: "Bearer YOUR_API_KEY"
      }
    }
  );

  console.log("Runs:", response.data.runs.length);
  return response.data.nextCursor;
}

listWorkflowRuns("550e8400-e29b-41d4-a716-446655440000");
```

## Response format

### Success response (200 OK)

```typescript theme={null}
{
  runs: Array<{
    id: string;
    runNumber: number;
    status: string;
    createdAt: string;
    updatedAt: string;
    isTestRun: boolean;
    isExecutionDataExpired: boolean;
    workflowVersion: {
      id: string;
      version: string;
      nodes: Array<object>;
      edges: Array<object>;
    };
    executions: Array<{
      id: string;
      workflowNodeId: string;
      createdAt: string;
      updatedAt: string;
      status: string;
      input: unknown;
      output: unknown;
      inputError: unknown;
      outputError: unknown;
      logs: unknown;
      durationMs: number;
      executionDataExpiredAt: string | null;
      accessDenied: boolean;
    }>;
    tags: Array<{ key: string; displayValue: string | null }>;
    rerunOf: { id: string; runNumber: number } | null;
    originalRerunOf: { id: string; runNumber: number } | null;
  }>;
  nextCursor?: string;
  hasWaitingForInput: boolean;
}
```

## Error handling

| Status code | Description |
| - | - |
| 400 | Invalid query, `from` without `to`, `to` earlier than `from`, or `runMode` that disagrees with `version` |
| 401 | Invalid or missing API key |
| 403 | Missing `WORKFLOW_API` scope or editor access. A missing workflow, a template, or a workflow in another workspace also returns this status. |
| 429 | Rate limit exceeded |
| 500 | Internal server error |

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml GET /workflows/v1/runs
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /workflows/v1/runs:
    get:
      tags:
        - Workflows
      summary: List workflow runs
      description: >-
        Returns paginated runs and node executions for a workflow the API key
        user can edit.
      operationId: listWorkflowRuns
      parameters:
        - name: workflowId
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: UUID of the workflow.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Number of runs to return.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Run UUID from nextCursor in the previous response.
        - name: runId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter to a single run UUID.
        - name: runMode
          in: query
          required: false
          schema:
            type: string
            enum:
              - test
              - production
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - IN_PROGRESS
              - AWAITING_INPUT
              - COMPLETED
              - FAILED
              - CANCELLED
        - name: from
          in: query
          required: false
          schema:
            type: string
          description: >-
            Start of the run creation range. ISO 8601 timestamp or YYYY-MM-DD.
            Must be sent together with to.
        - name: to
          in: query
          required: false
          schema:
            type: string
          description: End of the run creation range. Must be equal to or later than from.
        - name: version
          in: query
          required: false
          schema:
            type: string
          description: >-
            Workflow version used for the run. Version 0 is the draft used for
            test runs.
      responses:
        '200':
          description: Workflow runs returned successfully
        '400':
          description: >-
            Invalid query, from without to, to earlier than from, or runMode
            that disagrees with version
        '401':
          description: Invalid or missing API key
        '403':
          description: >-
            Missing WORKFLOW_API scope or editor access. A missing workflow, a
            template, or a workflow in another workspace also returns this
            status.
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.