List workflow runs - Upstash Documentation

curl https://qstash.upstash.io/v2/workflows/logs \
  -H "Authorization: Bearer <token>"

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// Filter by workflow run ID
const { runs } = await client.logs({ workflowRunId: "<WORKFLOW_RUN_ID>"});

// Filter by workflow server url
const { runs } = await client.logs({ workflowUrl: "<WORKFLOW_URL>"});

// Filter by state
const { runs } = await client.logs({ state: "RUN_SUCCESS"});

const response = await fetch("https://qstash.upstash.io/v2/workflows/logs", {
  headers: {
    Authorization: "Bearer <token>",
  },
});

import requests
headers = {
    'Authorization': 'Bearer <token>',
}

response = requests.get(
  'https://qstash.upstash.io/v2/workflows/logs',
  headers=headers
)

req, err := http.NewRequest("GET", "https://qstash.upstash.io/v2/workflows/logs", nil)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer <token>")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

{
  "cursor": "1686652644442-12",
  "runs": [
    {
      "workflowRunId": "wfr_rj0Upr1rvdzGfz96fXNHh",
      "workflowUrl": "https://feasible-eft-notably.ngrok-free.app/api/call",
      "workflowState": "RUN_SUCCESS",
      "workflowRunCreatedAt": 1736340463061,
      "workflowRunCompletedAt": 1736340464684,
      "steps": [
        {
          "steps": [
            {
              "stepName": "init",
              "stepType": "Initial",
              "callType": "step",
              "messageId": "msg_7YoJxFpwkEy5zBp378JgvD6YBDPBEqkBPje2JGTCEUiASMJQ1FwY9",
              "concurrent": 1,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463064
            }
          ],
          "type": "sequential"
        },
        {
          "steps": [
            {
              "stepId": 1,
              "stepName": "external call",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNCtiJGNsULmt63vFfcZxQ3sfYFKLZe2dKww4BSb2kVF",
              "out": "1",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340464111
            },
            {
              "stepId": 2,
              "stepName": "external call 2",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNB882AMRP1TsgzpygELRcLWep4ACNTTsCHhrZuaNLij",
              "out": "2",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463895
            }
          ],
          "type": "parallel"
        }
      ]
    }
  ]
}

GET

workflows

logs

curl https://qstash.upstash.io/v2/workflows/logs \
  -H "Authorization: Bearer <token>"

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// Filter by workflow run ID
const { runs } = await client.logs({ workflowRunId: "<WORKFLOW_RUN_ID>"});

// Filter by workflow server url
const { runs } = await client.logs({ workflowUrl: "<WORKFLOW_URL>"});

// Filter by state
const { runs } = await client.logs({ state: "RUN_SUCCESS"});

const response = await fetch("https://qstash.upstash.io/v2/workflows/logs", {
  headers: {
    Authorization: "Bearer <token>",
  },
});

import requests
headers = {
    'Authorization': 'Bearer <token>',
}

response = requests.get(
  'https://qstash.upstash.io/v2/workflows/logs',
  headers=headers
)

req, err := http.NewRequest("GET", "https://qstash.upstash.io/v2/workflows/logs", nil)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer <token>")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

{
  "cursor": "1686652644442-12",
  "runs": [
    {
      "workflowRunId": "wfr_rj0Upr1rvdzGfz96fXNHh",
      "workflowUrl": "https://feasible-eft-notably.ngrok-free.app/api/call",
      "workflowState": "RUN_SUCCESS",
      "workflowRunCreatedAt": 1736340463061,
      "workflowRunCompletedAt": 1736340464684,
      "steps": [
        {
          "steps": [
            {
              "stepName": "init",
              "stepType": "Initial",
              "callType": "step",
              "messageId": "msg_7YoJxFpwkEy5zBp378JgvD6YBDPBEqkBPje2JGTCEUiASMJQ1FwY9",
              "concurrent": 1,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463064
            }
          ],
          "type": "sequential"
        },
        {
          "steps": [
            {
              "stepId": 1,
              "stepName": "external call",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNCtiJGNsULmt63vFfcZxQ3sfYFKLZe2dKww4BSb2kVF",
              "out": "1",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340464111
            },
            {
              "stepId": 2,
              "stepName": "external call 2",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNB882AMRP1TsgzpygELRcLWep4ACNTTsCHhrZuaNLij",
              "out": "2",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463895
            }
          ],
          "type": "parallel"
        }
      ]
    }
  ]
}

You can fetch details about workflow runs, including their state, completed and in-progress steps, and step details. The retention duration for completed workflow runs depends on your quota. Please check the pricing page for details.

If you have executed multiple workflow runs with the same workflowRunId, the workflowRunId filter will return all of them.To uniquely identify a single workflow run, include the workflowCreatedAt timestamp in your filter.

Request

string

By providing a cursor you can paginate through all of the workflow runs.

string

Filter workflow runs by run id.

string

Filter workflow runs by workflow url.

number

Filter workflow runs by the unix milliseconds value of creation timestamp

string

Filter workflow runs by state

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.

number

Filter workflow runs by starting date, in milliseconds (Unix timestamp). This is inclusive.

number

Filter workflow runs by ending date, in milliseconds (Unix timestamp). This is inclusive.

number

The number of workflow runs to return. Default and max is 10.

string

Filter workflow run by the label assigned by the user.

Response

string

A cursor which you can use in subsequent requests to paginate through all workflow runs. If no cursor is returned, you have reached the end of the workflow runs.

Array

Show child attributes

string

The ID of the workflow run.

string

The URL address of the workflow endpoint.

string

The current state of the workflow run at this point in time

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.

number

The Unix timestamp (in milliseconds) when the workflow run started.

string

The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.

string

The label of the run assigned by the user on trigger.

FailureFunction

The details of the failure callback message, if a failure function was defined for the workflow.

Show child attributes

string

The ID of the failure callback message

string

The URL address of the failure function

string

The state of the failure callback

Value
`CALLBACK_INPROGRESS`
`CALLBACK_SUCCESS`
`CALLBACK_FAIL`

string

The HTTP headers of the message that triggered the failure function.

string

The HTTP response status of the message that triggered the failure function.

string

The response body of the message that triggered the failure function.

string

The DLQ ID of the workflow run.

string

Response body of the failure function/url. When failure function is used, this contains the returned message from the failure function.

array

Reponse headers of the failure function/url. This is valuable when the call to run the failure function/url is rejected because of a platform limit.

int

Reponse status of the failure function/url. This is valuable when the call to run the failure function/url is rejected because of a platform limit.

array

A call to failure url/function can be retried as maxRetries time. This array contains errors of all retry attempts.

Show child attributes

int

Response status of the endpoint that caused the error

array

Response Headers of the endpoint that caused the error

string

Response Body of the endpoint that caused the error if available

string

An error message that happened before/after calling the user's endpoint.

int64

The time of the error happened in Unix time milliseconds

string

Max number of retries configured when seeing an error.

Array

Hide child attributes

string

The type of grouped steps

Value	Description
`sequential`	Indicates only one step is excuted sequentially
`parallel`	Indicates multiple steps being executed in parallel.
`next`	Indicates there is information about currently executing step(s)

Array

Show child attributes

number

The ID of the step which increases monotonically.

string

The name of the step. It is specified in workflow by user.

string

Execution type of the step which indicates type of the context function.

Value	Function
`Initial`	The default step which created automatically
`Run`	context.run()
`Call`	context.call()
`SleepFor`	context.sleepFor()
`SleepUntil`	context.sleepUntil()
`Wait`	context.waitForEvent()
`Notify`	context.notify()
`Invoke`	context.invoke()

string

The ID of the message associated with this step.

string

The output returned by the step

string

The total number of concurrent steps that is running alongside this step

string

The state of this step at this point in time

Value
`STEP_SUCCESS`
`STEP_RETRY`
`STEP_FAILED`
`STEP_CANCELED`

string

The unix timestamp in milliseconds when the message associated with this step has created.

number

The unix timestamp in milliseconds when this step will be retried. This is set only when the step state is STEP_RETRY

The following fields are set only when a specific type of step is executing. These fields are not available for all step types.

string

The duration in milliseconds which step will sleep. Only set if stepType is SleepFor.

string

The unix timestamp (in milliseconds) which step will sleep until. Only set if stepType is SleepUntil.

string

The event id of the wait step. Only set if stepType is Wait.

string

The unix timestamp (in milliseconds) when the wait will time out.

string

The duration of timeout in human readable format (e.g. 120s, 1m, 1h).

string

Set to true if this step is cause of a wait timeout rather than notifying the waiter.

string

The URL of the external address. Available only if stepType is Call.

string

The HTTP method of the request sent to the external address. Available only if stepType is Call.

string

The HTTP headers of the request sent to the external address. Available only if stepType is Call.

string

The body of the request sent to the external address. Available only if stepType is Call.

number

The HTTP status returned by the external call. Available only if stepType is Call.

string

The body returned by the external call. Available only if stepType is Call.

array

The HTTP headers returned by the external call. Available only if stepType is Call.

string

The ID of the invoked workflow run if this step is an invoke step.

string

The URL address of the workflow server of invoked workflow run if this step is an invoke step.

number

The Unix timestamp (in milliseconds) when the invoked workflow was started if this step is an invoke step.

string

The body passed to the invoked workflow if this step is an invoke step.

string

The HTTP headers passed to invoked workflow if this step is an invoke step.

curl https://qstash.upstash.io/v2/workflows/logs \
  -H "Authorization: Bearer <token>"

import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

// Filter by workflow run ID
const { runs } = await client.logs({ workflowRunId: "<WORKFLOW_RUN_ID>"});

// Filter by workflow server url
const { runs } = await client.logs({ workflowUrl: "<WORKFLOW_URL>"});

// Filter by state
const { runs } = await client.logs({ state: "RUN_SUCCESS"});

const response = await fetch("https://qstash.upstash.io/v2/workflows/logs", {
  headers: {
    Authorization: "Bearer <token>",
  },
});

import requests
headers = {
    'Authorization': 'Bearer <token>',
}

response = requests.get(
  'https://qstash.upstash.io/v2/workflows/logs',
  headers=headers
)

req, err := http.NewRequest("GET", "https://qstash.upstash.io/v2/workflows/logs", nil)
if err != nil {
  log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer <token>")
resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

{
  "cursor": "1686652644442-12",
  "runs": [
    {
      "workflowRunId": "wfr_rj0Upr1rvdzGfz96fXNHh",
      "workflowUrl": "https://feasible-eft-notably.ngrok-free.app/api/call",
      "workflowState": "RUN_SUCCESS",
      "workflowRunCreatedAt": 1736340463061,
      "workflowRunCompletedAt": 1736340464684,
      "steps": [
        {
          "steps": [
            {
              "stepName": "init",
              "stepType": "Initial",
              "callType": "step",
              "messageId": "msg_7YoJxFpwkEy5zBp378JgvD6YBDPBEqkBPje2JGTCEUiASMJQ1FwY9",
              "concurrent": 1,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463064
            }
          ],
          "type": "sequential"
        },
        {
          "steps": [
            {
              "stepId": 1,
              "stepName": "external call",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNCtiJGNsULmt63vFfcZxQ3sfYFKLZe2dKww4BSb2kVF",
              "out": "1",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340464111
            },
            {
              "stepId": 2,
              "stepName": "external call 2",
              "stepType": "Run",
              "callType": "step",
              "messageId": "msg_26hZCxZCuWyyTWPmSVBrNB882AMRP1TsgzpygELRcLWep4ACNTTsCHhrZuaNLij",
              "out": "2",
              "concurrent": 2,
              "state": "STEP_SUCCESS",
              "createdAt": 1736340463895
            }
          ],
          "type": "parallel"
        }
      ]
    }
  ]
}

⌘I

​Request

​Response

Request

Response