---
title: "Await the completion of a test session"
method: GET
path: "/v1/test-sessions/{testSessionId}/completion"
tags: ["Test sessions"]
---

# Await the completion of a test session

`GET /v1/test-sessions/{testSessionId}/completion`

Call this endpoint to await the completion of a test session. A successful response code will be returned once the test session reaches its final state (i.e. when it passes or fails).

If the test session takes a long time to complete, the endpoint will return a timeout error code. You should keep calling the endpoint until you receive a successful response, or a non-timeout related error code. If using *curl*, its `--retry` option is suitable.

The successful response of this endpoint is equivalent to the `GET /v1/test-sessions/{testSessionId}` endpoint's response for a completed test session.

## Path parameters

- `testSessionId` string, uuid, required — Test session ID.

## Query parameters

- `maxWaitSeconds` number — Maximum time to wait for completion before returning a retryable timeout response.

## 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

- AwaitTestSessionCompletionResponse
  - `testSessionId` string, uuid, required
  - `testSessionLink` string, uri, required
  - `name` string, required
  - `status` 'FAILED' | 'PASSED' | 'CANCELLED', required
  - `errorGroupIds` string[], required — IDs of the test-session error groups observed in this test session.
  - `startedAt` string, date-time, required
  - `stoppedAt` string, date-time, required
  - `timeElapsed` number, required
  - `metadata` TestSessionMetadata
    - `environment` string — A short description for the testing environment.
    - `repoUrl` string, nullable
    - `commitId` string, nullable
    - `commitOwner` string, nullable
    - `commitMessage` string, nullable
    - `branchName` string, nullable
    - `github` TestSessionGitHubMetadata
      - `reporting` boolean, required
      - `repository` string, nullable
      - `sha` string, nullable
      - `runId` string, nullable
      - `runAttempt` string, nullable
      - `workflow` string, nullable
      - `job` string, nullable
      - `eventName` string, nullable
      - `ref` string, nullable
      - `headRef` string, nullable
      - `baseRef` string, nullable
      - `serverUrl` string, nullable
  - `results` TestSessionResult[]
    - `testSessionResultId` string, uuid, required
    - `testSessionResultLink` string, uri, required
    - `checkId` string, uuid, nullable
    - `checkType` 'AGENTIC' | 'API' | 'BROWSER' | 'HEARTBEAT' | 'ICMP' | 'MULTI_STEP' | 'TCP' | 'PLAYWRIGHT' | 'URL' | 'DNS' | 'SSL' | 'GRPC' | 'TRACEROUTE', required
    - `name` string
    - `runLocation` string
    - `errorGroupIds` string[], required — IDs of the test-session error groups associated with this result.
    - `resultType` 'FINAL' | 'ATTEMPT' | 'PENDING'
    - `status` 'RUNNING' | 'FAILED' | 'PASSED' | 'CANCELLED', required
    - `hasErrors` boolean, required
    - `hasFailures` boolean, required
    - `isDegraded` boolean, required
    - `aborted` boolean, required
    - `responseTime` number, nullable — Time the check spent producing its result, in milliseconds. For protocol checks this is the measured operation time (a subset of the run): request time for API and URL checks, connection time for TCP, resolution time for DNS, average latency for ICMP and TRACEROUTE, request timing for GRPC, and TLS handshake time for SSL. For browser, multi-step, Playwright and agentic checks it is the run wall-clock duration. Null until the check has finished. For the total wall-clock time a check run took, use `stoppedAt` - `startedAt`.
    - `startedAt` string, date-time, nullable — When the check run started. Null until the check has started.
    - `stoppedAt` string, date-time, nullable — When the check run finished. Subtract `startedAt` for the total wall-clock duration of the run. Null until the check has finished.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `408` — Request Timeout
- `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)