> ## Documentation Index > Fetch the complete documentation index at: https://checklyhq.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Trigger a new test session > 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. ## OpenAPI ````yaml post /v1/test-sessions/trigger 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/test-sessions/trigger: post: tags: - Test sessions - Triggers summary: Trigger a new test session description: >- 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. operationId: postV1TestsessionsTrigger parameters: - schema: type: string format: uuid description: >- Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general required: false description: >- Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general name: x-checkly-account in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TriggerTestSessionRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/TriggerTestSessionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '402': description: Payment Required content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: TriggerTestSessionRequest: type: object properties: name: type: string minLength: 1 description: The name of the test session. runLocation: type: string minLength: 1 description: A public region code or private location slug name. target: type: object properties: matchTags: type: array items: type: array items: type: string minLength: 1 description: >- Tags used to select checks to trigger. Each nested array is matched as one tag group. checkId: type: array items: type: string format: uuid description: Check ID or list of check IDs to trigger. allowDeactivated: type: boolean default: false description: Allow deactivated checks to match. environmentVariables: type: array items: $ref: '#/components/schemas/TestSessionEnvironmentVariable' maxItems: 50 retryStrategy: anyOf: - type: object properties: baseBackoffSeconds: type: number default: 60 sameRegion: type: boolean default: true onlyOn: type: array items: type: string enum: - NETWORK_ERROR type: type: string enum: - FIXED - LINEAR - EXPONENTIAL maxRetries: type: number minimum: 1 maximum: 10 default: 2 maxDurationSeconds: type: number minimum: 0 maximum: 600 default: 600 required: - type - type: object properties: baseBackoffSeconds: type: number default: 60 sameRegion: type: boolean default: true onlyOn: type: array items: type: string enum: - NETWORK_ERROR type: type: string enum: - SINGLE_RETRY required: - type - nullable: true refreshCache: type: boolean default: false description: Skip existing caches and install dependencies from scratch. metadata: $ref: '#/components/schemas/TestSessionMetadata' required: - name - runLocation TriggerTestSessionResponse: type: object properties: testSessionId: type: string format: uuid testSessionLink: type: string format: uri name: type: string status: type: string enum: - RUNNING - FAILED - PASSED - CANCELLED errorGroupIds: type: array items: type: string format: uuid description: IDs of the test-session error groups observed in this test session. startedAt: type: string nullable: false format: date-time stoppedAt: type: string nullable: true format: date-time timeElapsed: type: number metadata: $ref: '#/components/schemas/TestSessionMetadata' results: type: array items: $ref: '#/components/schemas/TestSessionResult' required: - testSessionId - testSessionLink - name - status - errorGroupIds - startedAt - timeElapsed ApiError: type: object properties: statusCode: type: number error: type: string message: type: string required: - statusCode - error - message TestSessionEnvironmentVariable: anyOf: - type: object properties: key: type: string minLength: 1 locked: type: boolean default: false value: nullable: true secret: type: boolean enum: - true required: - key - value - secret - type: object properties: key: type: string minLength: 1 locked: type: boolean default: false value: type: string nullable: true minLength: 1 secret: type: boolean enum: - false default: false required: - key - value TestSessionMetadata: type: object properties: environment: type: string minLength: 1 description: A short description for the testing environment. repoUrl: type: string nullable: true commitId: type: string nullable: true commitOwner: type: string nullable: true commitMessage: type: string nullable: true branchName: type: string nullable: true TestSessionResult: type: object properties: testSessionResultId: type: string format: uuid testSessionResultLink: type: string format: uri checkId: type: string nullable: true format: uuid checkType: type: string enum: - AGENTIC - API - BROWSER - HEARTBEAT - ICMP - MULTI_STEP - TCP - PLAYWRIGHT - URL - DNS name: type: string runLocation: type: string errorGroupIds: type: array items: type: string format: uuid description: IDs of the test-session error groups associated with this result. resultType: type: string enum: - FINAL - ATTEMPT - PENDING status: type: string enum: - RUNNING - FAILED - PASSED - CANCELLED hasErrors: type: boolean hasFailures: type: boolean isDegraded: type: boolean aborted: type: boolean required: - testSessionResultId - testSessionResultLink - checkType - errorGroupIds - status - hasErrors - hasFailures - isDegraded - aborted 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]"` ````