---
title: "Trigger a new check session"
method: POST
path: "/v2/check-sessions/trigger"
tags: ["Check sessions", "Triggers"]
---

# Trigger a new check session

`POST /v2/check-sessions/trigger`

Starts a check session for each check that matches the provided target filters. If no filters are given, matches all eligible checks.

This endpoint does not wait for the check session to complete. Use the `GET /v2/check-sessions/{checkSessionId}/completion` or `GET /v2/check-sessions/{checkSessionId}` endpoints to track progress.

Use `POST /v1/check-sessions/{checkSessionId}/cancel` to cancel an in-progress check session.

Standard alerting rules apply to finished check runs.

Equivalent to the _Schedule Now_ button in the UI.

## Headers

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

## Request body

- CheckSessionsV2TriggerRequest
  - `target` object — Optional filters selecting which checks to trigger.
    - `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.
  - `refreshCache` boolean — Refresh the selected checks cache before triggering the sessions.

## Response `201`

Created

- CheckSessionsV2TriggerResponse
  - `sessions` CheckSessionsV2CheckSession[], required
    - `checkSessionId` string, uuid, required
    - `checkSessionLink` string, uri, required
    - `checkId` string, uuid, required
    - `checkType` 'AGENTIC' | 'API' | 'BROWSER' | 'HEARTBEAT' | 'ICMP' | 'MULTI_STEP' | 'TCP' | 'PLAYWRIGHT' | 'URL' | 'DNS' | 'SSL' | 'GRPC' | 'TRACEROUTE', required
    - `name` string
    - `status` 'STARTED' | 'PROGRESS' | 'FAILED' | 'PASSED' | 'DEGRADED' | 'PROGRESS_FAILED' | 'PROGRESS_DEGRADED' | 'TIMED_OUT' | 'CANCELLED', required
    - `startedAt` string, date-time, required
    - `stoppedAt` string, date-time, nullable, required
    - `timeElapsed` number, required
    - `runLocations` string[], required
    - `runSource` 'CLI_DEPLOY' | 'DEPLOYMENT' | 'DEPLOYMENT_CACHE_WARMER' | 'EDITOR' | 'GROUP_RUN_ALL' | 'LEGACY_TRIGGER' | 'SCHEDULER' | 'SCHEDULE_NOW' | 'TEST_NO_RECORD' | 'TEST_RECORD' | 'TRIGGER_NO_RECORD' | 'TRIGGER_RECORD' | 'TRIGGER_API' | 'null', nullable, required

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