> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-playwright-vs-cypress-2026.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# checkly test-sessions

> Inspect recorded test sessions and their error groups.

<Note>Available since CLI v8.4.0.</Note>

The `checkly test-sessions` command lets you inspect recorded [test sessions](/detect/testing/overview/) from the terminal. Use it to list recent sessions, review a session, wait for a running session to finish, or inspect a test session error group before starting root cause analysis.

<Accordion title="Prerequisites">
  Before using `checkly test-sessions`, ensure you have:

  * Checkly CLI installed
  * Valid Checkly account authentication (run `npx checkly login` if needed)
  * A recorded test session ID

  For additional setup information, see [CLI overview](/cli/overview).
</Accordion>

## Usage

```bash Terminal theme={null}
npx checkly test-sessions <subcommand> [arguments] [options]
```

## Subcommands

| Subcommand | Description |
| - | - |
| `list` | List recorded test sessions. |
| `get` | Get details of a recorded test session. |

## `checkly test-sessions list`

<Note>The `checkly test-sessions list` command is only available since CLI v8.5.0.</Note>

List recorded test sessions for the currently selected account. Use filters to narrow by status, branch, user, or provider, and cursor pagination to page through results.

**Usage:**

```bash Terminal theme={null}
npx checkly test-sessions list [options]
```

**Options:**

| Option | Required | Description |
| - | - | - |
| `--limit, -l` | - | Number of test sessions to return (1-100). Default: `20`. |
| `--cursor` | - | Cursor for the next page (from previous output). |
| `--from` | - | Only include test sessions created at or after this ISO date or Unix timestamp. |
| `--to` | - | Only include test sessions created before this ISO date or Unix timestamp. |
| `--status` | - | Filter by status: `running`, `failed`, `passed`, or `cancelled`. Can be specified multiple times. |
| `--branch` | - | Filter by Git branch name. Can be specified multiple times. |
| `--user` | - | Filter by commit owner or invoking user ID. Can be specified multiple times. |
| `--no-users` | - | Include sessions with no commit owner and no invoking user. |
| `--provider` | - | Filter by provider: `github`, `vercel`, `api`, `trigger`, or `pw_reporter`. Can be specified multiple times. |
| `--search, -s` | - | Search test session text fields (3-200 characters). |
| `--error-group` | - | Filter by test-session error group ID. |
| `--output, -o` | - | Output format: `table`, `json`, or `md`. Default: `table`. |

### List Options

<ResponseField name="--limit, -l" type="number" default="20">
  Number of test sessions to return, between 1 and 100.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --limit=50
  npx checkly test-sessions list -l 10
  ```
</ResponseField>

<ResponseField name="--cursor" type="string">
  Cursor for paginating through results. Use the cursor value from the previous output, or the next-page command shown in table output.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --limit=20 --cursor=<cursor>
  ```
</ResponseField>

<ResponseField name="--from" type="string">
  Only include test sessions created at or after this point in time. Accepts an ISO date (such as `2026-06-01`) or a Unix timestamp in seconds.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --from=2026-06-01
  ```
</ResponseField>

<ResponseField name="--to" type="string">
  Only include test sessions created before this point in time. Accepts an ISO date or a Unix timestamp in seconds.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --from=2026-06-01 --to=2026-06-15
  ```
</ResponseField>

<ResponseField name="--status" type="string">
  Filter sessions by status. Available values: `running`, `failed`, `passed`, `cancelled`. Specify multiple times to match more than one status.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --status=failed
  npx checkly test-sessions list --status=failed --status=running
  ```
</ResponseField>

<ResponseField name="--branch" type="string">
  Filter sessions by Git branch name. Specify multiple times to match more than one branch.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --branch=main
  npx checkly test-sessions list --branch=main --branch=staging
  ```
</ResponseField>

<ResponseField name="--user" type="string">
  Filter sessions by commit owner or invoking user ID. Specify multiple times to match more than one user.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --user=<user-id>
  ```
</ResponseField>

<ResponseField name="--no-users" type="boolean">
  Include sessions that have no commit owner and no invoking user.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --no-users
  ```
</ResponseField>

<ResponseField name="--provider" type="string">
  Filter sessions by the provider that triggered them. Available values: `github`, `vercel`, `api`, `trigger`, `pw_reporter`. Specify multiple times to match more than one provider.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --provider=github
  npx checkly test-sessions list --provider=trigger --provider=api
  ```
</ResponseField>

<ResponseField name="--search, -s" type="string">
  Search test session text fields. The query must be between 3 and 200 characters.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --search="checkout flow"
  npx checkly test-sessions list -s "homepage"
  ```
</ResponseField>

<ResponseField name="--error-group" type="string">
  Filter sessions by a test-session error group ID.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --error-group=<error-group-id>
  ```
</ResponseField>

<ResponseField name="--output, -o" type="string" default="table">
  Set the output format. Use `json` for programmatic access or `md` for markdown.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions list --output=json
  npx checkly test-sessions list -o md
  ```
</ResponseField>

### List Examples

```bash Terminal theme={null}
# List recent test sessions
npx checkly test-sessions list

# Show only failed sessions
npx checkly test-sessions list --status=failed

# Filter by branch and provider
npx checkly test-sessions list --branch=main --provider=github

# Filter by a time range
npx checkly test-sessions list --from=2026-06-01 --to=2026-06-15

# Get results as JSON
npx checkly test-sessions list --output=json

# Page through results
npx checkly test-sessions list --limit=20 --cursor=<cursor>
```

## `checkly test-sessions get`

Get details of a recorded test session, including result error groups for RCA.

**Usage:**

```bash Terminal theme={null}
npx checkly test-sessions get <id> [options]
```

**Arguments:**

| Argument | Description |
| - | - |
| `id` | The ID of the test session to retrieve. |

**Options:**

| Option | Required | Description |
| - | - | - |
| `--result, -r` | - | Show details for a specific test session result ID. |
| `--error-group` | - | Show details for a test session error group ID from this session. |
| `--error-groups-limit` | - | Number of error group IDs to show in the session summary. Default: `5`. |
| `--full-error` | - | Print the complete raw error when showing a test session error group. |
| `--watch, -w` | - | Watch a running test session until it completes before rendering. |
| `--output, -o` | - | Output format: `detail`, `json`, or `md`. Default: `detail`. |

### Get Options

<ResponseField name="--result, -r" type="string">
  <Note>Available in CLI v8.7.0+.</Note>

  Drill into a specific test session result by its result ID. Shows detailed information for that result, including logs and timing data.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --result=<result-id>
  npx checkly test-sessions get <id> -r <result-id>
  ```
</ResponseField>

<ResponseField name="--error-group" type="string">
  Show details for a test session error group from the selected session. Use this after the session summary shows one or more error group IDs.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --error-group=<error-group-id>
  ```
</ResponseField>

<ResponseField name="--error-groups-limit" type="number" default="5">
  Set how many error group IDs to show in the session summary.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --error-groups-limit=10
  ```
</ResponseField>

<ResponseField name="--full-error" type="boolean" default="false">
  Print the complete raw error when you inspect a test session error group.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --error-group=<error-group-id> --full-error
  ```
</ResponseField>

<ResponseField name="--watch, -w" type="boolean" default="false">
  <Note>Available in CLI v8.5.0+.</Note>

  Watch a running test session until it reaches a final state before rendering the result.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --watch
  npx checkly test-sessions get <id> -w
  ```
</ResponseField>

<ResponseField name="--output, -o" type="string" default="detail">
  Set the output format. Use `json` for programmatic access or `md` for markdown.

  **Usage:**

  ```bash Terminal theme={null}
  npx checkly test-sessions get <id> --output=json
  npx checkly test-sessions get <id> -o md
  ```
</ResponseField>

### Get Examples

```bash Terminal theme={null}
# View a recorded test session
npx checkly test-sessions get <id>

# Wait for a running test session to complete
npx checkly test-sessions get <id> --watch

# Drill into a specific result
npx checkly test-sessions get <id> --result=<result-id>

# Inspect a test session error group
npx checkly test-sessions get <id> --error-group=<error-group-id>

# Get the session as JSON
npx checkly test-sessions get <id> --output=json
```

## Related Commands

* [`checkly trigger`](/cli/checkly-trigger) - Trigger deployed checks as a test session
* [`checkly test`](/cli/checkly-test) - Test local checks as a test session
* [`checkly rca`](/cli/checkly-rca) - Trigger root cause analysis for error groups
* [`checkly assets`](/cli/checkly-assets) - List and download result assets from a test session