--- title: "List Workflow Run Logs" method: GET path: "/v2/workflows/logs" tags: ["Logs"] --- # List Workflow Run Logs `GET /v2/workflows/logs` ## Request - Base URL: `https://qstash-eu-central-1.upstash.io` - URL: `https://qstash-eu-central-1.upstash.io/v2/workflows/logs` - Auth: one of: - HTTP bearer - API key in query parameter `qstash_token` - TypeScript: (a function with typed inputs; its response is checked against the schema) List and filter workflow runs with their state, completed and in-progress steps, and step details. ## Query parameters - `cursor` string - `workflowUrl` string - `workflowRunId` string - `workflowCreatedAt` integer - `workflowRuns` string - `state` string - `fromDate` integer - `toDate` integer - `count` integer - `trimBody` integer - `label` string[] - `flowControlKey` string - `callerIp` string ## Response `200` Workflow logs retrieved successfully - object - `cursor` string: Pagination cursor for the next page. Empty if no more results. - `runs` WorkflowRun[]: Array of complete workflow runs with all steps and metadata. - `workflowRunId` string: The unique identifier for this workflow run. - `workflowUrl` string: The URL of the workflow. - `workflowState` string: The current state of the workflow run | Value | Description | | -------------- | -------------------------------------------------------------- | | `RUN_STARTED` | The workflow has started to run and currently in progress. | | `RUN_SUCCESS` | The workflow run has completed succesfully. | | `RUN_FAILED` | Some errors has occured and workflow failed after all retries. | | `RUN_CANCELED` | The workflow run has canceled upon user request. | - `workflowRunCreatedAt` integer: When the workflow run was created (Unix timestamp in milliseconds). - `workflowRunCompletedAt` integer: When the workflow run completed (Unix timestamp in milliseconds). - `workflowRunCallerIp` string: IP address of the client who triggered the workflow. - `steps` GroupedSteps[]: The workflow steps grouped by execution pattern. - `steps` StepInfo[]: Array of steps in this group. - `stepId` integer: The unique identifier for this step. - `stepName` string: The name of the step. - `stepType` string: The type of step (e.g., call, wait, sleep, invoke). - `callType` string: The call type (e.g., step, parallelPlan, parallelResult). - `messageId` string: The message ID for this step. - `state` string: The state of the step (STEP_SUCCESS, STEP_RETRY, STEP_FAILED, STEP_PROGRESS, STEP_CANCELED). - `createdAt` integer: When the step was created (Unix timestamp in milliseconds). - `out` string: The output/result of the step. - `callUrl` string: The URL called in this step. - `callMethod` string: The HTTP method used. - `callBody` string: The request body sent. - `callHeaders` object: The request headers sent. - `callResponseStatus` integer: The HTTP status code received. - `callResponseBody` string: The response body received. - `callResponseHeaders` object: The response headers received. - `waitEventId` string: The event ID being waited for (wait steps only). - `waitTimeout` boolean: Whether the wait timed out. - `invokedWorkflowRunId` string: The run ID of the invoked workflow (invoke steps only). - `invokedWorkflowUrl` string: The URL of the invoked workflow. - `retries` integer: Maximum number of retries configured. - `nextDeliveryTime` integer: Next scheduled retry time (Unix timestamp in milliseconds). - `type` 'parallel' | 'sequential' | 'next': The type of grouping (parallel, sequential, or next). - `workflowRunResponse` string: The response returned by the workflow run. - `invoker` InvokerContext - `workflowRunId` string: The workflow run ID of the invoker. - `workflowUrl` string: The workflow URL of the invoker. - `workflowRunCreatedAt` integer: The creation timestamp of the invoker workflow run. - `failureFunction` FailureFunction - `messageId` string: The message ID of the failure callback. - `url` string: The URL of the failure callback. - `state` string: The state of the failure callback. - `dlqId` string: The DLQ ID of the failure callback if it failed. - `failHeaders` object: The headers from the failed workflow step. - `failStatus` integer: The status code from the failed workflow step. - `failResponse` string: The response body from the failed workflow step. - `responseBody` string: The response body from the failure callback attempt. - `responseHeaders` object: The response headers from the failure callback attempt. - `responseStatus` integer: The response status from the failure callback attempt. - `maxRetries` integer: Maximum number of retries configured for the failure callback. - `dlqId` string: The DLQ ID if the workflow run failed. - `label` string: Label assigned to the workflow run. Deprecated in favor of `labels`. - `labels` string[]: List of labels assigned to the workflow run. - `flowControlKey` string: Flow Control Key assigned to the workflow run. ## Other responses - `400`: Bad Request - Invalid parameters (e.g., invalid cursor, state, or groupBy value) - `401`: Unauthorized - `429`: Too Many Requests - Rate limit exceeded - `500`: Internal Server Error ## Changes - **2026-05-15** `4cbcb5c2eac1`: 3 info - for the `query` request parameter `label`, the type was generalized from `string` to `array` - added the optional property `runs/items/labels` to the response with the `200` status - response property `runs/items/label` deprecated - **2026-04-02** `be435bb79a55`: 1 info - added the new optional `query` request parameter `workflowRuns` [Operation history](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/changes/v2/workflows/logs/get.md) --- [API](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api.md) - [All operations](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upstash/apis/upstash-workflow-rest-api/revisions/251bee05a7ec?raw)