> ## 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 ``` **Dedicated deployments** Replace `api.langdock.com` with `/api/public` in all requests. ## 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; edges: Array; }; 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 | 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). ## 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" ````