Skip to main content
GET
/
v2
/
workflows
/
logs
List Workflow Run Logs
curl --request GET \
  --url https://qstash-{region}.upstash.io/v2/workflows/logs \
  --header 'Authorization: Bearer <token>'
{
  "cursor": "<string>",
  "runs": [
    {
      "workflowRunId": "<string>",
      "workflowUrl": "<string>",
      "workflowState": "<string>",
      "workflowRunCreatedAt": 123,
      "workflowRunCompletedAt": 123,
      "workflowRunCallerIp": "<string>",
      "steps": [
        {
          "steps": [
            {
              "stepId": 123,
              "stepName": "<string>",
              "stepType": "<string>",
              "callType": "<string>",
              "messageId": "<string>",
              "state": "<string>",
              "createdAt": 123,
              "out": "<string>",
              "callUrl": "<string>",
              "callMethod": "<string>",
              "callBody": "<string>",
              "callHeaders": {},
              "callResponseStatus": 123,
              "callResponseBody": "<string>",
              "callResponseHeaders": {},
              "waitEventId": "<string>",
              "waitTimeout": true,
              "invokedWorkflowRunId": "<string>",
              "invokedWorkflowUrl": "<string>",
              "retries": 123,
              "nextDeliveryTime": 123
            }
          ]
        }
      ],
      "workflowRunResponse": "<string>",
      "invoker": {
        "workflowRunId": "<string>",
        "workflowUrl": "<string>",
        "workflowRunCreatedAt": 123
      },
      "failureFunction": {
        "messageId": "<string>",
        "url": "<string>",
        "state": "<string>",
        "dlqId": "<string>",
        "failHeaders": {},
        "failStatus": 123,
        "failResponse": "<string>",
        "responseBody": "<string>",
        "responseHeaders": {},
        "responseStatus": 123,
        "maxRetries": 123
      },
      "dlqId": "<string>",
      "label": "<string>",
      "labels": [
        "<string>"
      ],
      "flowControlKey": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

QStash authentication token

Query Parameters

​
cursor
string

Pagination cursor for fetching the next page of results.

​
workflowUrl
string

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

​
workflowRunId
string

Filter by specific workflow run ID..

​
workflowCreatedAt
integer<int64>

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

​
workflowRuns
string

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.

​
state
string

Filter by workflow or step state. Common states include:

ValueDescription
RUN_STARTEDThe workflow has started to run and currently in progress.
RUN_SUCCESSThe workflow run has completed succesfully.
RUN_FAILEDSome errors has occured and workflow failed after all retries.
RUN_CANCELEDThe workflow run has canceled upon user request.
STEP_SUCCESSThe step succesfully fnished.
STEP_RETRYThe step is being retried.
STEP_FAILEDThe step is failed.
STEP_PROGRESSThe step is in progress.
STEP_CANCELEDThe step is cancelled manually.
​
fromDate
integer<int64>

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

​
toDate
integer<int64>

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

​
count
integer
default:1000

Maximum number of results to return per page.

  • Event mode: Max 1000 (default 1000)
  • Run mode (groupBy=workflowRunId): Max 10 (default 10)
Required range: x <= 1000
​
trimBody
integer
default:-1

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

​
label
string[]

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
​
flowControlKey
string

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

​
callerIp
string

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

Response

Workflow logs retrieved successfully

​
cursor
string

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

​
runs
object[]

Array of complete workflow runs with all steps and metadata.