List Workflow Run Logs - Upstash Documentation

GET/v2/workflows/logs

cURL

curl --request GET \
  --url https://qstash-{region}.upstash.io/v2/workflows/logs \
  --header 'Authorization: Bearer <token>'

200Response

{
  "cursor": "<string>",
  "runs": [
    {
      "workflowRunId": "<string>",
      "workflowUrl": "<string>",
      "workflowState": "<string>",
      "workflowRunCreatedAt": 123,
      "workflowRunCompletedAt": 123,
      "workflowRunCallerIp": "<string>",
      "steps": [
        {}
      ],
      "workflowRunResponse": "<string>",
      "invoker": {
        "workflowRunId": "<string>",
        "workflowUrl": "<string>",
        "workflowRunCreatedAt": 123
      },
      "failureFunction": {
        "messageId": "<string>",
        "url": "<string>",
        "state": "<string>",
        "dlqId": "<string>",
        "failHeaders": "<string>",
        "failStatus": 123,
        "failResponse": "<string>",
        "responseBody": "<string>",
        "responseHeaders": "<string>",
        "responseStatus": 123,
        "maxRetries": 123
      },
      "dlqId": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>"
    }
  ]
}

Authorization

Authorizationheaderstringrequired

Bearer authentication header of the form Bearer <token>.

Query parameters

cursorquerystring

Pagination cursor for fetching the next page of results.

workflowUrlquerystring

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

workflowRunIdquerystring

Filter by specific workflow run ID..

workflowCreatedAtqueryinteger

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

workflowRunsquerystring

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.

statequerystring

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.

fromDatequeryinteger

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

toDatequeryinteger

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

countqueryintegerdefault: 1000

Maximum number of results to return per page.

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

trimBodyqueryintegerdefault: -1

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

labelquerystring[]

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

flowControlKeyquerystring

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

callerIpquerystring

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

Response

200 — 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.

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.

stepsobject[]

Array of steps in this group.

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.

callResponseStatusinteger

The HTTP status code received.

callResponseBodystring

The response body received.

callResponseHeadersobject

The response headers received.

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).

Available options:parallelsequentialnext

workflowRunResponsestring

The response returned by the workflow run.

invokerobject

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

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.

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.

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.

400 — Bad Request - Invalid parameters (e.g., invalid cursor, state, or groupBy value)

errorstringrequired

Error message

401 — Unauthorized

errorstringrequired

Error message

429 — Too Many Requests - Rate limit exceeded

errorstringrequired

Error message

500 — Internal Server Error

errorstringrequired

Error message