---
title: "List test sessions"
method: GET
path: "/v1/test-sessions"
tags: ["Test sessions"]
---

# List test sessions

`GET /v1/test-sessions`

Retrieves test sessions for the selected account. Use the optional query parameters to filter by creation time, status, branch, user, provider, text, or error group.

## Query parameters

- `from` number — Only include test sessions created at or after this Unix timestamp.
- `to` number — Only include test sessions created before this Unix timestamp.
- `limit` integer, nullable — Maximum number of test sessions to return.
- `statuses` string[] — Filter by test session status.
- `branches` string[] — Filter by Git branch name.
- `users` string[] — Filter by commit owner or invoking user ID.
- `providers` string[] — Filter by test session provider.
- `noUsers` boolean — Include sessions with no commit owner and no invoking user.
- `nextId` string — Opaque cursor returned from a previous list response.
- `textSearch` string — Search test session text fields.
- `errorGroupId` string, nullable — Filter by test-session error group ID.

## Headers

- `x-checkly-account` string, uuid — Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

## Response `200`

Successful

- ListTestSessionsResponse
  - `length` integer, required
  - `entries` TestSessionListEntry[], required
    - `id` string, uuid, required
    - `accountId` string, uuid, required
    - `projectId` string, uuid, nullable
    - `name` string, required
    - `provider` string, required
    - `errorGroupIds` string[], nullable — IDs of the test-session error groups observed in this session. Pass one as `errorGroupId` (with type `test-session-error-group`) to get-error-group-root-cause-analyses or trigger-root-cause-analysis. This is the field that bridges a listed session to a root cause analysis.
    - `running` string[], nullable — Result sequence IDs (`sequenceId`) of in-progress results — not result IDs and not error-group IDs.
    - `passed` string[], nullable — Result sequence IDs (`sequenceId`) of passed results — not result IDs and not error-group IDs.
    - `failed` string[], nullable — Result sequence IDs (`sequenceId`) of failed results — NOT test-session result IDs and NOT error-group IDs. To act on a failed result, call get-test-session to enumerate its results (each with a `testSessionResultId` and `errorGroupIds`).
    - `cancelled` string[] — Result sequence IDs (`sequenceId`) of cancelled results — not result IDs and not error-group IDs.
    - `status` 'RUNNING' | 'FAILED' | 'PASSED' | 'CANCELLED'
    - `region` string, required
    - `privateLocationId` string, uuid, nullable
    - `invoker` TestSessionListEntryInvoker, nullable
      - `name` string, required
      - `picture` string, nullable
    - `repoUrl` string, nullable
    - `commitId` string, nullable
    - `commitOwner` string, nullable
    - `commitMessage` string, nullable
    - `branchName` string, nullable
    - `environment` string, nullable
    - `startedAt` string, date-time, required
    - `stoppedAt` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, nullable
  - `nextId` string, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `429` — Too Many Requests

---

[API](https://skmtc.net/checklyhq/apis/checkly-public-api.md) · [All operations](https://skmtc.net/checklyhq/apis/checkly-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/checklyhq/checkly-public-api/versions/9e903da4f3da/schema)