> ## 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.
# Workflow Run Export API
> Export workflow run and node execution data as JSON for analysis and debugging.
Use the Workflow Run Export API to export workflow run and node execution data as JSON. Each row gives you run metadata, node status, and detailed execution data when you have access to the node.
## Before you start
Before you start, make sure you have:
* **Workspace API key**: Create a workspace API key with the `WORKFLOW_API` scope under [Settings > Workspace > Products > API](/en/admin/workspace/workspace#api). Personal API keys only support the Completion APIs. See [Personal API keys](/en/using-langdock/account/personal-api-keys).
* **Workflow access**: The API key must belong to a workflow owner or editor. Workspace administrators can also access workflows without a workflow share. A workflow shared with the **User** role does not grant access to this endpoint, including for workspace administrators.
A workspace administrator's API key can export data across the workspace. An API key owned by a non-administrator is limited to workflows that person owns or can edit. Only grant this scope to trusted users.
## Base URL
```text theme={null}
https://api.langdock.com
```
```text theme={null}
https:///api/public
```
## Endpoint
```http theme={null}
GET /workflows/{workflowId}/runs
```
You receive one row for each node execution. A run without node executions returns one row with `null` node fields.
## Authentication
Send your API key as a Bearer token:
```bash cURL theme={null}
curl "https://api.langdock.com/workflows/550e8400-e29b-41d4-a716-446655440000/runs?from=2026-08-01&to=2026-08-31" \
-H "Authorization: Bearer YOUR_API_KEY"
```
For a dedicated deployment, replace `https://api.langdock.com` with your deployment base URL.
## Parameters
| Parameter | Location | Type | Required | Description |
| ------------ | -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workflowId` | Path | string | Yes | ID of the workflow to export. Must be a valid GUID. |
| `from` | Query | string | Yes | Start of the export range for the run creation time. Use an ISO 8601 date or timestamp. A date only value starts at `00:00:00.000` UTC. |
| `to` | Query | string | Yes | End of the export range for the run creation time. Use an ISO 8601 date or timestamp. A date only value ends at `23:59:59.999` UTC. The value must be equal to or later than `from`. |
Include `Z` or an explicit UTC offset in full timestamps. A timestamp without a timezone is interpreted in the server's local timezone. Both date values are required. The API does not apply a default date range. You receive every node execution for a matching run, even if the node execution falls outside the date range.
## Response
You receive a `data` array with flattened workflow run and node execution rows:
```json Success theme={null}
{
"data": [
{
"run_id": "7d2a1c4e-2f6a-4b9f-8c31-1a6d8e4f2b90",
"run_number": 42,
"run_status": "COMPLETED",
"run_created_at": "2026-08-12T09:15:00.000Z",
"run_updated_at": "2026-08-12T09:15:08.000Z",
"workflow_version": "3",
"trigger_mode": "WEBHOOK",
"node_execution_id": "2b8c1d4e-6f7a-4b90-9c12-3d5e7f8a1b20",
"node_id": "9c1f2d3e-7a4b-4c58-8d19-2e6f0b7a4c31",
"node_type": "agent",
"node_status": "COMPLETED",
"node_created_at": "2026-08-12T09:15:01.000Z",
"node_updated_at": "2026-08-12T09:15:06.000Z",
"failure_code": null,
"input": {
"customer_id": "customer-42"
},
"input_error": null,
"output": {
"category": "support"
},
"output_error": null,
"logs": [],
"data_redacted": false,
"execution_data_expired_at": null
}
]
}
```
Rows are ordered from oldest to newest by run creation time and then node execution creation time. The endpoint does not paginate. Use a narrower date range to reduce the response size.
### Response fields
| Field | Type | Description |
| --------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_id` | string | ID of the workflow run. |
| `run_number` | number | Sequential number of the run within the workflow. |
| `run_status` | string | Status of the workflow run: `PENDING`, `IN_PROGRESS`, `AWAITING_INPUT`, `COMPLETED`, `FAILED`, or `CANCELLED`. |
| `run_created_at` | string | Creation time of the workflow run in ISO 8601 format. |
| `run_updated_at` | string | Last update time of the workflow run in ISO 8601 format. |
| `workflow_version` | string | Version of the workflow used for the run. Version `0` is the draft workflow version. The public endpoint does not provide a test or production filter. |
| `trigger_mode` | string or null | Mode that triggered the run: `WEBHOOK`, `FORM`, `SCHEDULED`, `INTEGRATION_POLLING`, or `MANUAL`. |
| `node_execution_id` | string or null | ID of the node execution. |
| `node_id` | string or null | ID of the workflow node. |
| `node_type` | string or null | Type of the workflow node. |
| `node_status` | string or null | Status of the node execution: `NONE`, `IN_PROGRESS`, `AWAITING_INPUT`, `COMPLETED`, `FAILED`, or `CANCELLED`. |
| `node_created_at` | string or null | Creation time of the node execution in ISO 8601 format. |
| `node_updated_at` | string or null | Last update time of the node execution in ISO 8601 format. |
| `failure_code` | string or null | Failure code when the node execution fails. |
| `input` | JSON value or null | Input data for the node execution. |
| `input_error` | JSON value or null | Error data for the node input. |
| `output` | JSON value or null | Output data for the node execution. |
| `output_error` | JSON value or null | Error data for the node output. |
| `logs` | JSON value or null | Logs generated during the node execution. |
| `data_redacted` | boolean | Whether payload fields were omitted because you cannot access the node's data or the endpoint cannot establish access to it. |
| `execution_data_expired_at` | string or null | Time when detailed execution data expired, in ISO 8601 format. |
The `input` and `output` fields are `null` for execution data older than 30 days. All five payload fields are `null` when the endpoint cannot establish access to the node's data. This can happen when your workflow access does not include an action or agent node used by the execution. The API sets `data_redacted` to `true` in that case.
For payload values larger than 16,000 bytes, the API returns a truncation marker. The marker contains an `_truncated` object with `originalBytes`, `maxBytes`, and `message` fields.
The response does not include the identity of the person or group that triggered a run.
## Limits and retention
* Each request can export up to **10,000 workflow runs**.
* Input and output data is retained for **30 days**.
* Payload data in one response is limited to **8,000,000 bytes**.
If a request exceeds 10,000 runs, it returns `400 Bad Request` with the `WORKFLOW_RUN_EXPORT_LIMIT_EXCEEDED` code. If the payload data exceeds 8,000,000 bytes, it returns `400 Bad Request` with the `WORKFLOW_RUN_EXPORT_TOO_LARGE` code. Use a smaller date range to resolve either error.
## Rate limits
The endpoint allows **500 requests per minute** for each workspace and API key. Requests above the limit return `429 Too Many Requests`.
## Error handling
| Status code | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | The request is invalid. This includes an invalid workflow ID or date, a `to` value earlier than `from`, an export with more than 10,000 runs, or payload data larger than 8,000,000 bytes. |
| `401` | The API key is missing or invalid. |
| `403` | The API key does not have the `WORKFLOW_API` scope, or its owner is not the workflow owner, editor, or workspace administrator. A workflow **User** role does not grant access, including for workspace administrators. |
| `405` | The request uses a method other than `GET`. |
| `429` | The workspace and API key exceeded the request rate limit. |
| `500` | An unexpected server error occurred. |
```json Error theme={null}
{
"message": "Workflow run exports are limited to 10,000 runs. Select a smaller date range.",
"code": "WORKFLOW_RUN_EXPORT_LIMIT_EXCEEDED",
"details": {
"maxRuns": 10000
}
}
```
Malformed query parameters return `{"message":"Invalid request","errors":[...]}` without a `code` field. An invalid date or a `to` value earlier than `from` returns `code: "BAD_REQUEST"`.
Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, see [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml GET /workflows/{workflowId}/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/{workflowId}/runs:
get:
tags:
- Workflow Run Export
summary: Export workflow run data
description: |
Returns flattened workflow run and node execution rows for the selected
workflow. The date range filters workflow run creation time. The
endpoint requires a workspace API key with the `WORKFLOW_API` scope and
owner or editor access. Workspace administrators can access workflows
without a workflow share, but a User share does not grant access.
operationId: exportWorkflowRunData
parameters:
- name: workflowId
in: path
required: true
description: ID of the workflow to export.
schema:
type: string
format: uuid
- name: from
in: query
required: true
description: |
Start of the export range. Use an ISO 8601 date or timestamp. A
date-only value starts at 00:00:00.000 UTC.
schema:
type: string
example: '2026-08-01'
- name: to
in: query
required: true
description: |
End of the export range. Use an ISO 8601 date or timestamp. A
date-only value ends at 23:59:59.999 UTC.
schema:
type: string
example: '2026-08-31'
responses:
'200':
description: Workflow run export
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportResponse'
example:
data:
- run_id: 7d2a1c4e-2f6a-4b9f-8c31-1a6d8e4f2b90
run_number: 42
run_status: COMPLETED
run_created_at: '2026-08-12T09:15:00.000Z'
run_updated_at: '2026-08-12T09:15:08.000Z'
workflow_version: '3'
trigger_mode: WEBHOOK
node_execution_id: 2b8c1d4e-6f7a-4b90-9c12-3d5e7f8a1b20
node_id: 9c1f2d3e-7a4b-4c58-8d19-2e6f0b7a4c31
node_type: agent
node_status: COMPLETED
node_created_at: '2026-08-12T09:15:01.000Z'
node_updated_at: '2026-08-12T09:15:06.000Z'
failure_code: null
input:
customer_id: customer-42
input_error: null
output:
category: support
output_error: null
logs: []
data_redacted: false
execution_data_expired_at: null
'400':
description: Invalid request or export exceeds a configured limit
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportError'
example:
message: >-
Workflow run exports are limited to 10,000 runs. Select a
smaller date range.
code: WORKFLOW_RUN_EXPORT_LIMIT_EXCEEDED
details:
maxRuns: 10000
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportError'
'403':
description: Missing scope or workflow access
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportError'
'405':
description: Method not allowed
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowRunExportError'
security:
- bearerAuth: []
components:
schemas:
WorkflowRunExportResponse:
type: object
description: Flattened workflow run and node execution rows.
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/WorkflowRunExportRow'
WorkflowRunExportError:
type: object
description: Error response from the Workflow Run Export API.
properties:
message:
type: string
description: Error message.
code:
type: string
description: Machine-readable error code, when available.
details:
type: object
additionalProperties: true
description: Additional error context, when available.
errors:
type: array
items:
type: object
additionalProperties: true
description: Validation details for malformed query parameters.
required:
- message
WorkflowRunExportRow:
type: object
description: Data for one workflow run and its node execution.
required:
- run_id
- run_number
- run_status
- run_created_at
- run_updated_at
- workflow_version
- trigger_mode
- node_execution_id
- node_id
- node_type
- node_status
- node_created_at
- node_updated_at
- failure_code
- input
- input_error
- output
- output_error
- logs
- data_redacted
- execution_data_expired_at
properties:
run_id:
type: string
format: uuid
description: ID of the workflow run.
run_number:
type: integer
description: Sequential number of the run within the workflow.
run_status:
type: string
enum:
- PENDING
- IN_PROGRESS
- AWAITING_INPUT
- COMPLETED
- FAILED
- CANCELLED
description: Status of the workflow run.
run_created_at:
type: string
format: date-time
description: Creation time of the workflow run.
run_updated_at:
type: string
format: date-time
description: Last update time of the workflow run.
workflow_version:
type: string
description: Version of the workflow used for the run.
trigger_mode:
type: string
nullable: true
enum:
- WEBHOOK
- FORM
- SCHEDULED
- INTEGRATION_POLLING
- MANUAL
description: Mode that triggered the run.
node_execution_id:
type: string
format: uuid
nullable: true
description: ID of the node execution.
node_id:
type: string
format: uuid
nullable: true
description: ID of the workflow node.
node_type:
type: string
nullable: true
description: Type of the workflow node.
node_status:
type: string
nullable: true
enum:
- NONE
- IN_PROGRESS
- AWAITING_INPUT
- COMPLETED
- FAILED
- CANCELLED
description: Status of the node execution.
node_created_at:
type: string
format: date-time
nullable: true
description: Creation time of the node execution.
node_updated_at:
type: string
format: date-time
nullable: true
description: Last update time of the node execution.
failure_code:
type: string
nullable: true
description: Failure code when the node execution fails.
input:
nullable: true
description: Input data for the node execution.
oneOf:
- type: object
additionalProperties: true
- type: array
items: {}
- type: string
- type: number
- type: boolean
input_error:
nullable: true
description: Error data for the node input.
oneOf:
- type: object
additionalProperties: true
- type: array
items: {}
- type: string
- type: number
- type: boolean
output:
nullable: true
description: Output data for the node execution.
oneOf:
- type: object
additionalProperties: true
- type: array
items: {}
- type: string
- type: number
- type: boolean
output_error:
nullable: true
description: Error data for the node output.
oneOf:
- type: object
additionalProperties: true
- type: array
items: {}
- type: string
- type: number
- type: boolean
logs:
nullable: true
description: Logs generated during the node execution.
oneOf:
- type: object
additionalProperties: true
- type: array
items: {}
- type: string
- type: number
- type: boolean
data_redacted:
type: boolean
description: >-
Whether payload fields were omitted because access to the node data
could not be established.
execution_data_expired_at:
type: string
format: date-time
nullable: true
description: Time when detailed execution data expired.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````