> ## Documentation index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Search it with GET https://upstash.com/docs/search?q=<query>.
> Use these to discover all available pages before exploring further.

# client.logs

The `logs` method retrieves workflow run logs using the [List Workflow Runs API](/workflow/api-reference/logs/list-workflow-run-logs).

## Arguments

<ParamField body="cursor" type="string" optional>
    A pagination cursor from a previous request.
    Use this to fetch the next set of results.
</ParamField>

<ParamField body="count" type="number" optional>
    Maximum number of runs to return. Defaults to a system-defined value if not specified.
</ParamField>

<ParamField body="filter" type="object" optional>
    Filter options for narrowing down workflow run logs.

    <Expandable defaultOpen>
        <ParamField body="workflowRunId" type="string" optional>
            Filter by a specific workflow run ID.
        </ParamField>

        <ParamField body="state" type="string" optional>
            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.           |
        </ParamField>

        <ParamField body="workflowUrl" type="string" optional>
            Filter by the exact workflow URL.
        </ParamField>

        <ParamField body="label" type="string | string[]" optional>
            Filter by workflow label. Pass an array to match runs that have any
            of the given labels (OR semantics).
        </ParamField>

        <ParamField body="workflowCreatedAt" type="number" optional>
            Filter by the workflow creation time (Unix timestamp).
        </ParamField>

        <ParamField body="messageId" type="string" optional>
            Filter by a specific message ID.
        </ParamField>

        <ParamField body="fromDate" type="Date | number" optional>
            Filter workflow runs created after this date.
        </ParamField>

        <ParamField body="toDate" type="Date | number" optional>
            Filter workflow runs created before this date.
        </ParamField>

        <ParamField body="callerIp" type="string" optional>
            Filter by the IP address that triggered the workflow.
        </ParamField>

        <ParamField body="flowControlKey" type="string" optional>
            Filter by flow control key.
        </ParamField>
    </Expandable>
</ParamField>

## Response

<ResponseField name="cursor" type="string">
    A cursor to use for pagination.
    If no cursor is returned, there are no more workflow runs.
</ResponseField>

<ResponseField name="runs" type="Array">
  <Expandable>
    <ResponseField name="workflowRunId" type="string">
        The ID of the workflow run.
    </ResponseField>

    <ResponseField name="workflowUrl" type="string">
        The URL address of the workflow endpoint.
    </ResponseField>

    <ResponseField name="workflowState" type="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.               |

    </ResponseField>

    <ResponseField name="workflowCreatedAt" type="number">
      The Unix timestamp (in milliseconds) when the workflow run started.
    </ResponseField>

    <ResponseField name="workflowRunCompletedAt" type="string">
        The Unix timestamp (in milliseconds) when the workflow run was completed, if applicable.
    </ResponseField>

    <ResponseField name="labels" type="string[]">
    The labels of the run assigned by the user on trigger.
    </ResponseField>

    <ResponseField name="label" type="string" deprecated>
    Deprecated. Use `labels` instead. When a run has multiple labels, this only
    contains the first one.
    </ResponseField>

    <ResponseField name="failureFunction" type="FailureFunction">
      The details of the failure callback message, if a failure function was defined for the workflow.

      <Expandable  defaultClosed>
        <ResponseField name="messageId" type="string">
          The ID of the failure callback message
        </ResponseField>

        <ResponseField name="url" type="string">
          The URL address of the failure function
        </ResponseField>

        <ResponseField name="state" type="string">
          The state of the failure callback

          | Value                 |
          | --------------------- |
          | `CALLBACK_INPROGRESS` |
          | `CALLBACK_SUCCESS`    |
          | `CALLBACK_FAIL`       |

        </ResponseField>

        <ResponseField name="failHeaders" type="string">
          The HTTP headers of the message that triggered the failure function.
        </ResponseField>

        <ResponseField name="failStatus" type="string">
          The HTTP response status of the message that triggered the failure function.
        </ResponseField>

        <ResponseField name="failResponse" type="string">
          The response body of the message that triggered the failure function.
        </ResponseField>

        <ResponseField name="dlqId" type="string">
          The DLQ ID of the workflow run.
        </ResponseField>

        <ResponseField name="responseBody" type="string">
          Response body of the failure function/url.
          When [failure function](/workflow/basics/serve#failurefunction) is used, this contains
          the returned message from the failure function.
        </ResponseField>

        <ResponseField name="responseHeaders" type="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.
        </ResponseField>

        <ResponseField name="responseStatus" type="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.
        </ResponseField>

        <ResponseField name="errors" type="array">
          A call to failure url/function can be retried as `maxRetries` time. This array contains errors of all retry
          attempts.

          <Expandable>
            <ResponseField name="status" type="int">
              Response status of the endpoint that caused the error
            </ResponseField>

            <ResponseField name="headers" type="array">
              Response Headers of the endpoint that caused the error
            </ResponseField>

            <ResponseField name="body" type="string">
              Response Body of the endpoint that caused the error if available
            </ResponseField>

            <ResponseField name="error" type="string">
              An error message that happened before/after calling the user's endpoint.
            </ResponseField>

            <ResponseField name="time" type="int64">
                The time of the error happened in Unix time milliseconds
            </ResponseField>

          </Expandable>
        </ResponseField>

        <ResponseField name="maxRetries" type="string">
          Max number of retries configured when seeing an error.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="steps" type="Array">

      <Expandable  defaultOpen>
        <ResponseField name="type" type="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) |

        </ResponseField>

        <ResponseField name="steps" type="Array">
          <Expandable  defaultClosed>
            <ResponseField name="stepId" type="number" >
              The ID of the step which increases monotonically.
            </ResponseField>

            <ResponseField name="stepName" type="string" >
              The name of the step. It is specified in workflow by user.
            </ResponseField>

            <ResponseField name="stepType" type="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()                             |
            </ResponseField>

            <ResponseField name="messageId" type="string" >
                The ID of the message associated with this step.
            </ResponseField>

            <ResponseField name="out" type="string" >
                The output returned by the step
            </ResponseField>

            <ResponseField name="concurrent" type="string" >
                The total number of concurrent steps that is running alongside this step
            </ResponseField>

            <ResponseField name="state" type="string" >
                The state of this step at this point in time

                | Value           |
                | --------------- |
                | `STEP_SUCCESS`  |
                | `STEP_RETRY`    |
                | `STEP_FAILED`   |
                | `STEP_CANCELED` |
            </ResponseField>

            <ResponseField name="createdAt" type="string" >
              The unix timestamp in milliseconds when the message associated with this step has created.
            </ResponseField>

            <ResponseField name="nextDeliveryTime" type="number">
              The unix timestamp in milliseconds when this step will be retried.
              This is set only when the step state is `STEP_RETRY`
            </ResponseField>

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

            <ResponseField name="sleepFor" type="string" >
              The duration in milliseconds which step will sleep. Only set if stepType is `SleepFor`.
            </ResponseField>

            <ResponseField name="sleepUntil" type="string" >
              The unix timestamp (in milliseconds) which step will sleep until. Only set if stepType is `SleepUntil`.
            </ResponseField>

            <ResponseField name="waitEventId" type="string" >
              The event id of the wait step. Only set if stepType is `Wait`.
            </ResponseField>

            <ResponseField name="waitTimeoutDeadline" type="string" >
              The unix timestamp (in milliseconds) when the wait will time out.
            </ResponseField>

            <ResponseField name="waitTimeoutDuration" type="string">
              The duration of timeout in human readable format (e.g. 120s, 1m, 1h).
            </ResponseField>

            <ResponseField name="waitTimeout" type="string" >
              Set to true if this step is cause of a wait timeout rather than notifying the waiter.
            </ResponseField>

            <ResponseField name="callUrl" type="string">
                The URL of the external address. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callMethod" type="string">
                The HTTP method of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callHeaders" type="string">
                The HTTP headers of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callBody" type="string">
                The body of the request sent to the external address. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callResponseStatus" type="number">
                The HTTP status returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callResponseBody" type="string">
                The body returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="callResponseHeaders" type="array">
                The HTTP headers returned by the external call. Available only if stepType is `Call`.
            </ResponseField>

            <ResponseField name="invokedWorkflowRunId" type="string">
              The ID of the invoked workflow run if this step is an invoke step.
            </ResponseField>

            <ResponseField name="invokedWorkflowUrl" type="string">
              The URL address of the workflow server of invoked workflow run if this step is an invoke step.
            </ResponseField>

            <ResponseField name="invokedWorkflowCreatedAt" type="number">
              The Unix timestamp (in milliseconds) when the invoked workflow was started if this step is an invoke step.
            </ResponseField>

            <ResponseField name="invokedWorkflowRunBody" type="string">
              The body passed to the invoked workflow if this step is an invoke step.
            </ResponseField>

            <ResponseField name="invokedWorkflowRunHeaders" type="string">
              The HTTP headers passed to invoked workflow if this step is an invoke step.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

---

## Usage

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

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

const { runs, cursor } = await client.logs()
```

### Paginate with cursor

```ts
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

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

### Filter by label and date range

```ts
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.

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