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

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



## OpenAPI

````yaml post /v2/check-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:
  /v2/check-sessions/trigger:
    post:
      tags:
        - Check sessions
        - Triggers
      summary: Trigger a new check session
      description: >-
        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.
      operationId: postV2ChecksessionsTrigger
      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/CheckSessionsV2TriggerRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckSessionsV2TriggerResponse'
        '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:
    CheckSessionsV2TriggerRequest:
      type: object
      properties:
        target:
          type: object
          properties:
            matchTags:
              type: array
              items:
                type: array
                items:
                  type: string
              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.
          description: Optional filters selecting which checks to trigger.
        refreshCache:
          type: boolean
          default: false
          description: Refresh the selected checks cache before triggering the sessions.
    CheckSessionsV2TriggerResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/CheckSessionsV2CheckSession'
      required:
        - sessions
    ApiError:
      type: object
      properties:
        statusCode:
          type: number
        error:
          type: string
        message:
          type: string
      required:
        - statusCode
        - error
        - message
    CheckSessionsV2CheckSession:
      type: object
      properties:
        checkSessionId:
          type: string
          format: uuid
        checkSessionLink:
          type: string
          format: uri
        checkId:
          type: string
          format: uuid
        checkType:
          type: string
          enum:
            - AGENTIC
            - API
            - BROWSER
            - HEARTBEAT
            - ICMP
            - MULTI_STEP
            - TCP
            - PLAYWRIGHT
            - URL
            - DNS
        name:
          type: string
        status:
          type: string
          enum:
            - STARTED
            - PROGRESS
            - FAILED
            - PASSED
            - DEGRADED
            - PROGRESS_FAILED
            - PROGRESS_DEGRADED
            - TIMED_OUT
            - CANCELLED
        startedAt:
          type: string
          nullable: false
          format: date-time
        stoppedAt:
          type: string
          nullable: true
          format: date-time
        timeElapsed:
          type: number
        runLocations:
          type: array
          items:
            type: string
        runSource:
          type: string
          nullable: true
          enum:
            - 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
      required:
        - checkSessionId
        - checkSessionLink
        - checkId
        - checkType
        - status
        - startedAt
        - stoppedAt
        - timeElapsed
        - runLocations
        - runSource
  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]"` 

````