client.logs - Upstash Documentation

The logs method retrieves workflow run logs using the List Workflow Runs API.

Arguments#

cursorstring#

A pagination cursor from a previous request. Use this to fetch the next set of results.

countnumber#

Maximum number of runs to return. Defaults to a system-defined value if not specified.

filterobject#

Filter options for narrowing down workflow run logs.

Show properties

workflowRunIdstring#

Filter by a specific workflow run ID.

statestring#

Filter workflow runs by execution state.

State	Description
`RUN_STARTED`	The workflow run is in progress.
`RUN_SUCCESS`	The workflow run completed successfully.
`RUN_FAILED`	The run failed after all retries.
`RUN_CANCELED`	The run was manually canceled.

workflowUrlstring#

Filter by the exact workflow URL.

labelstring | string[]#

Filter by workflow label. Pass an array to match runs that have any of the given labels (OR semantics).

workflowCreatedAtnumber#

Filter by the workflow creation time (Unix timestamp).

messageIdstring#

Filter by a specific message ID.

fromDateDate | number#

Filter workflow runs created after this date.

toDateDate | number#

Filter workflow runs created before this date.

callerIpstring#

Filter by the IP address that triggered the workflow.

flowControlKeystring#

Filter by flow control key.

Response#

cursorstring#

A cursor to use for pagination. If no cursor is returned, there are no more workflow runs.

runsArray#

Show properties

workflowRunIdstring#

The ID of the workflow run.

workflowUrlstring#

The URL address of the workflow endpoint.

workflowStatestring#

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.

workflowCreatedAtnumber#

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

workflowRunCompletedAtstring#

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

labelsstring[]#

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

labelstringdeprecated#

Deprecated. Use labels instead. When a run has multiple labels, this only contains the first one.

failureFunctionFailureFunction#

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

Show properties

messageIdstring#

The ID of the failure callback message

urlstring#

The URL address of the failure function

statestring#

The state of the failure callback

Value
`CALLBACK_INPROGRESS`
`CALLBACK_SUCCESS`
`CALLBACK_FAIL`

failHeadersstring#

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

failStatusstring#

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

failResponsestring#

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

dlqIdstring#

The DLQ ID of the workflow run.

responseBodystring#

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

responseHeadersarray#

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.

responseStatusint#

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.

errorsarray#

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

Show properties

statusint#

Response status of the endpoint that caused the error

headersarray#

Response Headers of the endpoint that caused the error

bodystring#

Response Body of the endpoint that caused the error if available

errorstring#

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

timeint64#

The time of the error happened in Unix time milliseconds

maxRetriesstring#

Max number of retries configured when seeing an error.

stepsArray#

Show properties

typestring#

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)

stepsArray#

Show properties

stepIdnumber#

The ID of the step which increases monotonically.

stepNamestring#

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

stepTypestring#

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

messageIdstring#

The ID of the message associated with this step.

outstring#

The output returned by the step

concurrentstring#

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

statestring#

The state of this step at this point in time

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

createdAtstring#

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

nextDeliveryTimenumber#

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.

sleepForstring#

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

sleepUntilstring#

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

waitEventIdstring#

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

waitTimeoutDeadlinestring#

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

waitTimeoutDurationstring#

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

waitTimeoutstring#

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

callUrlstring#

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

callMethodstring#

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

callHeadersstring#

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

callBodystring#

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

callResponseStatusnumber#

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

callResponseBodystring#

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

callResponseHeadersarray#

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

invokedWorkflowRunIdstring#

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

invokedWorkflowUrlstring#

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

invokedWorkflowCreatedAtnumber#

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

invokedWorkflowRunBodystring#

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

invokedWorkflowRunHeadersstring#

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

Usage#

import { Client } from "@upstash/workflow";const client = new Client({ token: "<QSTASH_TOKEN>" })const { runs, cursor } = await client.logs()

Paginate with cursor#

const allRuns = [];let cursor: string | undefined;do {  const result = await client.logs({ cursor });  allRuns.push(...result.runs);  cursor = result.cursor;} while (cursor);

Filter by state#

const { runs } = await client.logs({  filter: {    state: "RUN_FAILED",  }})

Filter by label and date range#

const { runs } = await client.logs({  filter: {    label: "my-workflow",    fromDate: new Date("2024-01-01"),    toDate: new Date("2024-06-01"),  }})

Filter by multiple labels#

Passing an array matches runs that have any of the given labels (OR semantics). For example, with runs labelled ["label-1", "label-2"] and ["label-2", "label-3"], filtering by ["label-1", "label-2"] returns both.

const { runs } = await client.logs({  filter: {    label: ["label-1", "label-2"],  }})