---
title: "Trigger a new test session"
method: POST
path: "/v1/test-sessions/trigger"
tags: ["Test sessions", "Triggers"]
---

# Trigger a new test session

`POST /v1/test-sessions/trigger`

Starts a tests session with checks matching the provided target filters. If no filters are given, matches all eligible checks.

This endpoint does not wait for the test session to complete. Use the `GET /v1/test-sessions/{testSessionId}/completion` or `GET /v1/test-sessions/{testSessionId}` endpoints to track progress if needed.

Test sessions do not produce alerts.

Equivalent to the `npx checkly trigger` command of the Checkly CLI.

## Headers

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

## Request body

- TriggerTestSessionRequest
  - `name` string, required — The name of the test session.
  - `runLocation` string, required — A public region code or private location slug name.
  - `target` object
    - `matchTags` array[] — Tags used to select checks to trigger. Each nested array is matched as one tag group.
      - string[]
    - `checkId` string[] — Check ID or list of check IDs to trigger.
    - `allowDeactivated` boolean — Allow deactivated checks to match.
  - `environmentVariables` TestSessionEnvironmentVariable[]
    - union
      - object
        - `key` string, required
        - `locked` boolean
        - `value` unknown, required
        - `secret` true, required
      - object
        - `key` string, required
        - `locked` boolean
        - `value` string, nullable, required
        - `secret` false
  - `retryStrategy` union
    - object
      - `baseBackoffSeconds` number
      - `sameRegion` boolean
      - `onlyOn` string[]
      - `type` 'FIXED' | 'LINEAR' | 'EXPONENTIAL', required
      - `maxRetries` number
      - `maxDurationSeconds` number
    - object
      - `baseBackoffSeconds` number
      - `sameRegion` boolean
      - `onlyOn` string[]
      - `type` 'SINGLE_RETRY', required
    - unknown
  - `refreshCache` boolean — Skip existing caches and install dependencies from scratch.
  - `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

## Response `201`

Created

- TriggerTestSessionResponse
  - `testSessionId` string, uuid, required
  - `testSessionLink` string, uri, required
  - `name` string, required
  - `status` 'RUNNING' | '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, nullable
  - `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
- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found
- `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/revisions/87d29dc7b4fe/schema)