> ## Documentation Index > Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Await the completion of a check session > Call this endpoint to await the completion of a check session. A successful response will be returned once the check session reaches its final state (i.e. when it passes or fails). If the check 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/check-sessions/{checkSessionId}` endpoint's response for a completed check session. ## OpenAPI ````yaml get /v1/check-sessions/{checkSessionId}/completion openapi: 3.0.0 info: title: Checkly Public API version: v1 description: >- These are the docs for the newly released Checkly Public API. If you have any questions, please do not hesitate to get in touch with us. servers: - url: https://api.checklyhq.com security: - Bearer: [] tags: [] paths: /v1/check-sessions/{checkSessionId}/completion: get: tags: - Check sessions summary: Await the completion of a check session description: >- Call this endpoint to await the completion of a check session. A successful response will be returned once the check session reaches its final state (i.e. when it passes or fails). If the check 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/check-sessions/{checkSessionId}` endpoint's response for a completed check session. operationId: getV1ChecksessionsChecksessionidCompletion parameters: - name: checkSessionId in: path schema: type: string description: The unique identifier of the check session. x-format: guid: true description: The unique identifier of the check session. required: true - name: maxWaitSeconds in: query schema: type: number description: The maximum time to wait for completion, in seconds. example: 30 minimum: 1 maximum: 30 description: The maximum time to wait for completion, in seconds. responses: '200': description: Returned when the check session has finished running. content: application/json: schema: $ref: '#/components/schemas/AwaitCheckSessionCompletionResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: No such check session exists. content: application/json: schema: $ref: '#/components/schemas/CheckSessionNotFoundErrorResponse' '408': description: >- The check session is still pending, but the server requests a quick break. You should call the endpoint again. Optionally, try to respect the `Retry-After` header. This error code is one of the transient error codes supported by *curl*'s `--retry` option. content: application/json: schema: $ref: >- #/components/schemas/AwaitCheckSessionCompletionTryAgainResponse '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' deprecated: true components: schemas: AwaitCheckSessionCompletionResponse: type: object description: Returned when the check session has finished running. properties: checkSessionId: type: string description: The unique identifier of the check session. example: 8166fa86-c9b4-4162-8541-d380c6c212d8 x-format: guid: true checkSessionLink: type: string description: A link to the check session. example: >- https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8 x-format: uri: true checkId: type: string description: The ID of the check. example: a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a x-format: guid: true checkType: $ref: '#/components/schemas/Model94' name: type: string example: Example API Check status: $ref: '#/components/schemas/Model95' startedAt: type: string format: date-time description: The date and time when the session started. example: '2025-08-28T18:23:40.262Z' stoppedAt: type: string format: date-time description: The date and time when the session stopped. example: '2025-08-28T18:28:40.993Z' timeElapsed: type: number description: The time the check session took, in milliseconds. example: 300731 runLocations: $ref: '#/components/schemas/runLocations' runSource: $ref: '#/components/schemas/runSource' results: $ref: '#/components/schemas/Model96' required: - checkSessionId - checkSessionLink - checkId - checkType - status - startedAt - stoppedAt - timeElapsed - runLocations UnauthorizedError: type: object properties: statusCode: type: number enum: - 401 error: $ref: '#/components/schemas/error' message: type: string example: Bad Token attributes: $ref: '#/components/schemas/attributes' required: - statusCode - error ForbiddenError: type: object properties: statusCode: type: number enum: - 403 error: $ref: '#/components/schemas/Model1' message: type: string example: Forbidden required: - statusCode - error CheckSessionNotFoundErrorResponse: type: object description: No such check session exists. properties: statusCode: type: number enum: - 404 error: type: string example: Not Found message: type: string example: No such check session. required: - statusCode AwaitCheckSessionCompletionTryAgainResponse: type: object description: >- The check session is still pending, but the server requests a quick break. You should call the endpoint again. Optionally, try to respect the `Retry-After` header. This error code is one of the transient error codes supported by *curl*'s `--retry` option. properties: statusCode: type: number enum: - 408 error: type: string example: Request Time-out message: type: string example: >- Check session is still in progress, but maximum per-request wait time was exceeded. Please retry. required: - statusCode TooManyRequestsError: type: object properties: statusCode: type: number enum: - 429 error: $ref: '#/components/schemas/Model2' message: type: string example: Too Many Requests attributes: $ref: '#/components/schemas/attributes' required: - statusCode - error Model94: type: string example: API enum: - AGENTIC - API - BROWSER - ICMP - MULTI_STEP - TCP - PLAYWRIGHT - TRACEROUTE - URL - DNS - SSL - GRPC Model95: type: string description: The final status of the check session. example: PASSED enum: - FAILED - PASSED - DEGRADED - TIMED_OUT - CANCELLED runLocations: type: array description: The run locations of the check session. example: - us-east-1 - eu-central-1 items: type: string runSource: type: string description: The source that triggered the check session. example: TRIGGER_API enum: - CLI_DEPLOY - DEPLOYMENT - DEPLOYMENT_CACHE_WARMER - EDITOR - GROUP_RUN_ALL - LEGACY_TRIGGER - SCHEDULER - SCHEDULE_NOW - SLACK_RERUN - TEST_NO_RECORD - TEST_RECORD - TRIGGER_NO_RECORD - TRIGGER_RECORD - TRIGGER_API nullable: true Model96: type: array description: The results of the check session. items: $ref: '#/components/schemas/CheckSessionConciseCheckResult' error: type: string enum: - Unauthorized attributes: type: object Model1: type: string enum: - Forbidden Model2: type: string enum: - Too Many Requests CheckSessionConciseCheckResult: type: object properties: checkResultId: type: string description: The ID of the check result. example: 22be3b52-5ec2-4894-9086-b5b4a8b00a89 x-format: guid: true checkResultLink: type: string description: A link to the check result. example: >- https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8/results/22be3b52-5ec2-4894-9086-b5b4a8b00a89 x-format: uri: true checkId: type: string description: The ID of the check. example: a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a x-format: guid: true checkType: $ref: '#/components/schemas/Model92' name: type: string example: Example API Check runLocation: type: string description: The location where the check ran. example: us-east-1 resultType: $ref: '#/components/schemas/Model93' hasErrors: type: boolean description: Whether the result has errors. example: false hasFailures: type: boolean description: Whether the result has failures. example: false isDegraded: type: boolean description: Whether the result is degraded. example: false aborted: type: boolean description: Whether the check was aborted. example: false isCancelled: type: boolean description: Whether the check was cancelled before completion. example: false responseTime: type: number description: >- 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. example: 1234 nullable: true startedAt: type: string format: date-time description: The date and time when the check run started. example: '2025-08-28T18:23:40.262Z' nullable: true stoppedAt: type: string format: date-time description: >- The date and time when the check run finished. Subtract startedAt for the total wall-clock duration of the run. example: '2025-08-28T18:23:41.496Z' nullable: true required: - checkResultId - checkResultLink - checkId - checkType - runLocation - resultType - hasErrors - hasFailures - isDegraded - aborted - isCancelled Model92: type: string example: API enum: - AGENTIC - API - BROWSER - ICMP - MULTI_STEP - TCP - PLAYWRIGHT - TRACEROUTE - URL - DNS - SSL - GRPC Model93: type: string description: The type of the result. example: FINAL enum: - FINAL - ATTEMPT - ALL nullable: true securitySchemes: Bearer: type: http scheme: bearer bearerFormat: Bearer description: >- The Checkly Public API uses API keys to authenticate requests. You can get the API Key [here](https://app.checklyhq.com/settings/user/api-keys). Your API key is like a password: keep it secure! Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID. For example, set **Authorization** header while using cURL: `curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"` ````