Skip to main content
POST
/
v1
/
check-sessions
/
trigger
Trigger a new check session
curl --request POST \
  --url https://api.checklyhq.com/v1/check-sessions/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target": {
    "matchTags": [
      [
        "production",
        "!skip-e2e"
      ]
    ],
    "checkId": [
      "a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a"
    ]
  },
  "refreshCache": false
}
'
import requests

url = "https://api.checklyhq.com/v1/check-sessions/trigger"

payload = {
    "target": {
        "matchTags": [["production", "!skip-e2e"]],
        "checkId": ["a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a"]
    },
    "refreshCache": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    target: {
      matchTags: [['production', '!skip-e2e']],
      checkId: ['a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a']
    },
    refreshCache: false
  })
};

fetch('https://api.checklyhq.com/v1/check-sessions/trigger', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checklyhq.com/v1/check-sessions/trigger",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'target' => [
        'matchTags' => [
                [
                                'production',
                                '!skip-e2e'
                ]
        ],
        'checkId' => [
                'a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a'
        ]
    ],
    'refreshCache' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checklyhq.com/v1/check-sessions/trigger"

	payload := strings.NewReader("{\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"production\",\n        \"!skip-e2e\"\n      ]\n    ],\n    \"checkId\": [\n      \"a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a\"\n    ]\n  },\n  \"refreshCache\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.checklyhq.com/v1/check-sessions/trigger")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"production\",\n        \"!skip-e2e\"\n      ]\n    ],\n    \"checkId\": [\n      \"a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a\"\n    ]\n  },\n  \"refreshCache\": false\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.checklyhq.com/v1/check-sessions/trigger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"production\",\n        \"!skip-e2e\"\n      ]\n    ],\n    \"checkId\": [\n      \"a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a\"\n    ]\n  },\n  \"refreshCache\": false\n}"

response = http.request(request)
puts response.read_body
{
  "sessions": [
    {
      "checkSessionId": "8166fa86-c9b4-4162-8541-d380c6c212d8",
      "checkSessionLink": "https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8",
      "checkId": "a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a",
      "checkType": "API",
      "status": "PASSED",
      "startedAt": "2025-08-28T18:23:40.262Z",
      "timeElapsed": 300731,
      "runLocations": [
        "us-east-1",
        "eu-central-1"
      ],
      "name": "Example API Check",
      "stoppedAt": "2025-08-28T18:28:40.993Z",
      "runSource": "TRIGGER_API"
    }
  ]
}
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Bad Token",
  "attributes": {}
}
{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Payment Required",
  "attributes": {}
}
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Forbidden"
}
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No matching checks were found."
}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too Many Requests",
  "attributes": {}
}

Authorizations

​
Authorization
string
header
required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here. 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]"

Body

application/json
​
target
object
​
refreshCache
boolean
default:false

If true, the runner will skip existing caches and install dependencies from scratch. This applies only to Playwright Check Suites.

Response

Returns a check session for each check matching target conditions.

Returns a check session for each check matching target conditions.

​
sessions
object[]
required

A list of check sessions, with one check session for each check.