# checkly test-sessions - Checkly Docs > Inspect recorded test sessions and their error groups. Source: https://www.checklyhq.com/docs/cli/checkly-test-sessions/ --- - Usage - Subcommands - checkly test-sessions list List Options - List Examples - checkly test-sessions get Get Options - Get Examples - Related Commands CLI Commands # checkly test-sessions Inspect recorded test sessions and their error groups. Available since CLI v8.4.0. The `checkly test-sessions` command lets you inspect recorded [test sessions](https://www.checklyhq.com/docs/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. 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](https://www.checklyhq.com/docs/cli/overview). ## ​ Usage Terminal ``` npx checkly test-sessions [arguments] [options] ``` ## ​ Subcommands Subcommand Description `list` List recorded test sessions. `get` Get details of a recorded test session. ## ​ `checkly test-sessions list` The `checkly test-sessions list` command is only available since CLI v8.5.0. 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:** Terminal ``` 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 ​ number default: "20" Number of test sessions to return, between 1 and 100. **Usage:** Terminal ``` npx checkly test-sessions list --limit=50 npx checkly test-sessions list -l 10 ``` ​ string Cursor for paginating through results. Use the cursor value from the previous output, or the next-page command shown in table output. **Usage:** Terminal ``` npx checkly test-sessions list --limit=20 --cursor= ``` ​ 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:** Terminal ``` npx checkly test-sessions list --from=2026-06-01 ``` ​ string Only include test sessions created before this point in time. Accepts an ISO date or a Unix timestamp in seconds. **Usage:** Terminal ``` npx checkly test-sessions list --from=2026-06-01 --to=2026-06-15 ``` ​ string Filter sessions by status. Available values: `running`, `failed`, `passed`, `cancelled`. Specify multiple times to match more than one status. **Usage:** Terminal ``` npx checkly test-sessions list --status=failed npx checkly test-sessions list --status=failed --status=running ``` ​ string Filter sessions by Git branch name. Specify multiple times to match more than one branch. **Usage:** Terminal ``` npx checkly test-sessions list --branch=main npx checkly test-sessions list --branch=main --branch=staging ``` ​ string Filter sessions by commit owner or invoking user ID. Specify multiple times to match more than one user. **Usage:** Terminal ``` npx checkly test-sessions list --user= ``` ​ boolean Include sessions that have no commit owner and no invoking user. **Usage:** Terminal ``` npx checkly test-sessions list --no-users ``` ​ 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:** Terminal ``` npx checkly test-sessions list --provider=github npx checkly test-sessions list --provider=trigger --provider=api ``` ​ string Search test session text fields. The query must be between 3 and 200 characters. **Usage:** Terminal ``` npx checkly test-sessions list --search="checkout flow" npx checkly test-sessions list -s "homepage" ``` ​ string Filter sessions by a test-session error group ID. **Usage:** Terminal ``` npx checkly test-sessions list --error-group= ``` ​ string default: "table" Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal ``` npx checkly test-sessions list --output=json npx checkly test-sessions list -o md ``` ### ​ List Examples Terminal ``` # 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= ``` ## ​ `checkly test-sessions get` Get details of a recorded test session, including result error groups for RCA. **Usage:** Terminal ``` npx checkly test-sessions get [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 ​ string Available in CLI v8.7.0+. Drill into a specific test session result by its result ID. Shows detailed information for that result, including logs and timing data. **Usage:** Terminal ``` npx checkly test-sessions get --result= npx checkly test-sessions get -r ``` ​ 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:** Terminal ``` npx checkly test-sessions get --error-group= ``` ​ number default: "5" Set how many error group IDs to show in the session summary. **Usage:** Terminal ``` npx checkly test-sessions get --error-groups-limit=10 ``` ​ boolean default: "false" Print the complete raw error when you inspect a test session error group. **Usage:** Terminal ``` npx checkly test-sessions get --error-group= --full-error ``` ​ boolean default: "false" Available in CLI v8.5.0+. Watch a running test session until it reaches a final state before rendering the result. **Usage:** Terminal ``` npx checkly test-sessions get --watch npx checkly test-sessions get -w ``` ​ string default: "detail" Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal ``` npx checkly test-sessions get --output=json npx checkly test-sessions get -o md ``` ### ​ Get Examples Terminal ``` # View a recorded test session npx checkly test-sessions get # Wait for a running test session to complete npx checkly test-sessions get --watch # Drill into a specific result npx checkly test-sessions get --result= # Inspect a test session error group npx checkly test-sessions get --error-group= # Get the session as JSON npx checkly test-sessions get --output=json ``` ## ​ Related Commands - [`checkly trigger`](https://www.checklyhq.com/docs/cli/checkly-trigger) - Trigger deployed checks as a test session - [`checkly test`](https://www.checklyhq.com/docs/cli/checkly-test) - Test local checks as a test session - [`checkly rca`](https://www.checklyhq.com/docs/cli/checkly-rca) - Trigger root cause analysis for error groups - [`checkly assets`](https://www.checklyhq.com/docs/cli/checkly-assets) - List and download result assets from a test session Was this page helpful? [Suggest edits](https://github.com/checkly/docs/edit/main/cli/checkly-test-sessions.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/checkly-test-sessions) [checkly test Previous](https://www.checklyhq.com/docs/cli/checkly-test)[checkly trigger Next](https://www.checklyhq.com/docs/cli/checkly-trigger) [x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly) [Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)