List Workflow Run Logs

1 min read

get/v2/workflows/logs

Request example

curl --request GET \
  --url https://qstash-eu-central-1.upstash.io/v2/workflows/logs?cursor=%3Cstring%3E&workflowUrl=%3Cstring%3E&workflowRunId=%3Cstring%3E&workflowCreatedAt=1&workflowRuns=%3Cstring%3E&state=%3Cstring%3E&fromDate=1&toDate=1&count=1000&trimBody=-1&label=%3Cstring%3E&flowControlKey=%3Cstring%3E&callerIp=%3Cstring%3E \
  --header 'Authorization: Bearer <token>'

Response

{
  "cursor": "<string>",
  "runs": [
    {
      "workflowRunId": "<string>",
      "workflowUrl": "<string>",
      "workflowState": "<string>",
      "workflowRunCreatedAt": 1,
      "workflowRunCompletedAt": 1,
      "workflowRunCallerIp": "<string>",
      "steps": [
        {
          "steps": [
            {
              "stepId": 1,
              "stepName": "<string>",
              "stepType": "<string>",
              "callType": "<string>",
              "messageId": "<string>",
              "state": "<string>",
              "createdAt": 1,
              "out": "<string>",
              "callUrl": "<string>",
              "callMethod": "<string>",
              "callBody": "<string>",
              "callHeaders": {},
              "callResponseStatus": 1,
              "callResponseBody": "<string>",
              "callResponseHeaders": {},
              "waitEventId": "<string>",
              "waitTimeout": true,
              "invokedWorkflowRunId": "<string>",
              "invokedWorkflowUrl": "<string>",
              "retries": 1,
              "nextDeliveryTime": 1
            }
          ],
          "type": "parallel"
        }
      ],
      "workflowRunResponse": "<string>",
      "invoker": {
        "workflowRunId": "<string>",
        "workflowUrl": "<string>",
        "workflowRunCreatedAt": 1
      },
      "failureFunction": {
        "messageId": "<string>",
        "url": "<string>",
        "state": "<string>",
        "dlqId": "<string>",
        "failHeaders": {},
        "failStatus": 1,
        "failResponse": "<string>",
        "responseBody": "<string>",
        "responseHeaders": {},
        "responseStatus": 1,
        "maxRetries": 1
      },
      "dlqId": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>"
    }
  ]
}

get/v2/workflows/logs

Authorization

Authorizationstringheaderrequired#

QStash authentication token

1 alternative authorization method available — see the spec for details.

Query parameters

cursorstring#

Pagination cursor for fetching the next page of results.

workflowUrlstring#

Filter by workflow URL (exact match). Must start with http:// or https://.

workflowRunIdstring#

Filter by specific workflow run ID..

workflowCreatedAtinteger#

Filter by workflow creation timestamp in milliseconds (Unix timestamp).

workflowRunsstring#

Filter by multiple workflow runs. Provide a comma-separated list of workflowRunId@workflowCreatedAt pairs to query specific runs in a single request.

Example: workflowRuns=ID1@TS1,ID2@TS2

When this parameter is provided, all other filters are ignored.

statestring#

Filter by workflow or step state. Common states include:

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.
`STEP_SUCCESS`	The step succesfully fnished.
`STEP_RETRY`	The step is being retried.
`STEP_FAILED`	The step is failed.
`STEP_PROGRESS`	The step is in progress.
`STEP_CANCELED`	The step is cancelled manually.

fromDateinteger#

Filter events from this date onwards in milliseconds (Unix timestamp). Inclusive.

toDateinteger#

Filter events up to this date in milliseconds (Unix timestamp). Inclusive.

countinteger#

Maximum number of results to return per page.

Event mode: Max 1000 (default 1000)
Run mode (groupBy=workflowRunId): Max 10 (default 10)

Default: 1000

Range: <= 1000

trimBodyinteger#

Trim request/response bodies to this many bytes. Use -1 to exclude bodies entirely.
Useful for reducing response size when bodies are large.

Default: -1

labelstring[]#

Filter workflow run by label. Supports multi-value filtering. You can pass multiple values to match workflow runs with any of the given labels (OR logic).

Examples:

label=my_label
label=label_1&label=label_2

flowControlKeystring#

Filter workflow run by the flow control key assigned by the user on trigger.

callerIpstring#

Filter workflow run by the callerIp that started to workflow run.

Responses

application/json

Workflow logs retrieved successfully

cursorstring#

Pagination cursor for the next page. Empty if no more results.

runsobject[]#

Array of complete workflow runs with all steps and metadata.

Show child attributes

workflowRunIdstring#

The unique identifier for this workflow run.

workflowUrlstring#

The URL of the workflow.

workflowStatestring#

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.

workflowRunCreatedAtinteger#

When the workflow run was created (Unix timestamp in milliseconds).

workflowRunCompletedAtinteger#

When the workflow run completed (Unix timestamp in milliseconds).

workflowRunCallerIpstring#

IP address of the client who triggered the workflow.

stepsobject[]#

The workflow steps grouped by execution pattern.

Show child attributes

stepsobject[]#

Array of steps in this group.

Show child attributes

stepIdinteger#

The unique identifier for this step.

stepNamestring#

The name of the step.

stepTypestring#

The type of step (e.g., call, wait, sleep, invoke).

callTypestring#

The call type (e.g., step, parallelPlan, parallelResult).

messageIdstring#

The message ID for this step.

statestring#

The state of the step (STEP_SUCCESS, STEP_RETRY, STEP_FAILED, STEP_PROGRESS, STEP_CANCELED).

createdAtinteger#

When the step was created (Unix timestamp in milliseconds).

outstring#

The output/result of the step.

callUrlstring#

The URL called in this step.

callMethodstring#

The HTTP method used.

callBodystring#

The request body sent.

callHeadersobject#

The request headers sent.

Show child attributes

{key}string[]#

callResponseStatusinteger#

The HTTP status code received.

callResponseBodystring#

The response body received.

callResponseHeadersobject#

The response headers received.

Show child attributes

{key}string[]#

waitEventIdstring#

The event ID being waited for (wait steps only).

waitTimeoutboolean#

Whether the wait timed out.

invokedWorkflowRunIdstring#

The run ID of the invoked workflow (invoke steps only).

invokedWorkflowUrlstring#

The URL of the invoked workflow.

retriesinteger#

Maximum number of retries configured.

nextDeliveryTimeinteger#

Next scheduled retry time (Unix timestamp in milliseconds).

typeenum<string>#

The type of grouping (parallel, sequential, or next).

Options:parallelsequentialnext

workflowRunResponsestring#

The response returned by the workflow run.

invokerobject#

Show child attributes

workflowRunIdstring#

The workflow run ID of the invoker.

workflowUrlstring#

The workflow URL of the invoker.

workflowRunCreatedAtinteger#

The creation timestamp of the invoker workflow run.

failureFunctionobject#

Show child attributes

messageIdstring#

The message ID of the failure callback.

urlstring#

The URL of the failure callback.

statestring#

The state of the failure callback.

dlqIdstring#

The DLQ ID of the failure callback if it failed.

failHeadersobject#

The headers from the failed workflow step.

Show child attributes

{key}string[]#

failStatusinteger#

The status code from the failed workflow step.

failResponsestring#

The response body from the failed workflow step.

responseBodystring#

The response body from the failure callback attempt.

responseHeadersobject#

The response headers from the failure callback attempt.

Show child attributes

{key}string[]#

responseStatusinteger#

The response status from the failure callback attempt.

maxRetriesinteger#

Maximum number of retries configured for the failure callback.

dlqIdstring#

The DLQ ID if the workflow run failed.

labelstringdeprecated#

Label assigned to the workflow run. Deprecated in favor of labels.

labelsstring[]#

List of labels assigned to the workflow run.

flowControlKeystring#

Flow Control Key assigned to the workflow run.

Bulk Cancel Workflow Runs List Failed Workflow Runs