> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-partnerstash.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List workflow runs

> Fetch details about workflow runs

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](https://upstash.com/pricing/workflow) page for details.

<Note>
  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.
</Note>

## Request

<ParamField query="cursor" type="string">
  By providing a cursor you can paginate through all of the workflow runs.
</ParamField>

<ParamField query="workflowRunId" type="string">
  Filter workflow runs by run id.
</ParamField>

<ParamField query="workflowUrl" type="string">
  Filter workflow runs by workflow url.
</ParamField>

<ParamField query="workflowCreatedAt" type="number">
  Filter workflow runs by the unix milliseconds value of creation timestamp
</ParamField>

<ParamField query="state" type="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.               |
</ParamField>

<ParamField query="fromDate" type="number">
  Filter workflow runs by starting date, in milliseconds (Unix timestamp). This is inclusive.
</ParamField>

<ParamField query="toDate" type="number">
  Filter workflow runs by ending date, in milliseconds (Unix timestamp). This is inclusive.
</ParamField>

<ParamField query="count" type="number">
  The number of workflow runs to return. Default and max is 10.
</ParamField>

<ResponseField name="label" type="string">
  Filter workflow run by the label assigned by the user.
</ResponseField>

## Response

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

<Snippet file="workflow/logs.mdx" />

<RequestExample>
  ```sh curl theme={null}
  curl https://qstash.upstash.io/v2/workflows/logs \
    -H "Authorization: Bearer <token>"
  ```

  ```js Workflow JS SDK theme={null}
  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"});
  ```

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

  ```python Python theme={null}
  import requests
  headers = {
      'Authorization': 'Bearer <token>',
  }

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

  ```go Go theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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"
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>