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.

POST /v1/test-sessions/trigger

Trigger a new test session

cURL

curl --request POST \
  --url https://api.checklyhq.com/v1/test-sessions/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "runLocation": "<string>",
  "target": {
    "matchTags": [
      [
        "<string>"
      ]
    ],
    "checkId": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "allowDeactivated": false
  },
  "environmentVariables": [
    {
      "key": "<string>",
      "value": null,
      "secret": true,
      "locked": false
    }
  ],
  "retryStrategy": {
    "baseBackoffSeconds": 60,
    "sameRegion": true,
    "onlyOn": [
      "NETWORK_ERROR"
    ],
    "maxRetries": 2,
    "maxDurationSeconds": 600
  },
  "refreshCache": false,
  "metadata": {
    "environment": "<string>",
    "repoUrl": "<string>",
    "commitId": "<string>",
    "commitOwner": "<string>",
    "commitMessage": "<string>",
    "branchName": "<string>"
  }
}
'

import requests

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

payload = {
    "name": "<string>",
    "runLocation": "<string>",
    "target": {
        "matchTags": [["<string>"]],
        "checkId": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
        "allowDeactivated": False
    },
    "environmentVariables": [
        {
            "key": "<string>",
            "value": None,
            "secret": True,
            "locked": False
        }
    ],
    "retryStrategy": {
        "baseBackoffSeconds": 60,
        "sameRegion": True,
        "onlyOn": ["NETWORK_ERROR"],
        "maxRetries": 2,
        "maxDurationSeconds": 600
    },
    "refreshCache": False,
    "metadata": {
        "environment": "<string>",
        "repoUrl": "<string>",
        "commitId": "<string>",
        "commitOwner": "<string>",
        "commitMessage": "<string>",
        "branchName": "<string>"
    }
}
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({
    name: '<string>',
    runLocation: '<string>',
    target: {
      matchTags: [['<string>']],
      checkId: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
      allowDeactivated: false
    },
    environmentVariables: [{key: '<string>', value: null, secret: true, locked: false}],
    retryStrategy: {
      baseBackoffSeconds: 60,
      sameRegion: true,
      onlyOn: ['NETWORK_ERROR'],
      maxRetries: 2,
      maxDurationSeconds: 600
    },
    refreshCache: false,
    metadata: {
      environment: '<string>',
      repoUrl: '<string>',
      commitId: '<string>',
      commitOwner: '<string>',
      commitMessage: '<string>',
      branchName: '<string>'
    }
  })
};

fetch('https://api.checklyhq.com/v1/test-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/test-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([
    'name' => '<string>',
    'runLocation' => '<string>',
    'target' => [
        'matchTags' => [
                [
                                '<string>'
                ]
        ],
        'checkId' => [
                '3c90c3cc-0d44-4b50-8888-8dd25736052a'
        ],
        'allowDeactivated' => false
    ],
    'environmentVariables' => [
        [
                'key' => '<string>',
                'value' => null,
                'secret' => true,
                'locked' => false
        ]
    ],
    'retryStrategy' => [
        'baseBackoffSeconds' => 60,
        'sameRegion' => true,
        'onlyOn' => [
                'NETWORK_ERROR'
        ],
        'maxRetries' => 2,
        'maxDurationSeconds' => 600
    ],
    'refreshCache' => false,
    'metadata' => [
        'environment' => '<string>',
        'repoUrl' => '<string>',
        'commitId' => '<string>',
        'commitOwner' => '<string>',
        'commitMessage' => '<string>',
        'branchName' => '<string>'
    ]
  ]),
  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/test-sessions/trigger"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"runLocation\": \"<string>\",\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"<string>\"\n      ]\n    ],\n    \"checkId\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"allowDeactivated\": false\n  },\n  \"environmentVariables\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": null,\n      \"secret\": true,\n      \"locked\": false\n    }\n  ],\n  \"retryStrategy\": {\n    \"baseBackoffSeconds\": 60,\n    \"sameRegion\": true,\n    \"onlyOn\": [\n      \"NETWORK_ERROR\"\n    ],\n    \"maxRetries\": 2,\n    \"maxDurationSeconds\": 600\n  },\n  \"refreshCache\": false,\n  \"metadata\": {\n    \"environment\": \"<string>\",\n    \"repoUrl\": \"<string>\",\n    \"commitId\": \"<string>\",\n    \"commitOwner\": \"<string>\",\n    \"commitMessage\": \"<string>\",\n    \"branchName\": \"<string>\"\n  }\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/test-sessions/trigger")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"runLocation\": \"<string>\",\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"<string>\"\n      ]\n    ],\n    \"checkId\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"allowDeactivated\": false\n  },\n  \"environmentVariables\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": null,\n      \"secret\": true,\n      \"locked\": false\n    }\n  ],\n  \"retryStrategy\": {\n    \"baseBackoffSeconds\": 60,\n    \"sameRegion\": true,\n    \"onlyOn\": [\n      \"NETWORK_ERROR\"\n    ],\n    \"maxRetries\": 2,\n    \"maxDurationSeconds\": 600\n  },\n  \"refreshCache\": false,\n  \"metadata\": {\n    \"environment\": \"<string>\",\n    \"repoUrl\": \"<string>\",\n    \"commitId\": \"<string>\",\n    \"commitOwner\": \"<string>\",\n    \"commitMessage\": \"<string>\",\n    \"branchName\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checklyhq.com/v1/test-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  \"name\": \"<string>\",\n  \"runLocation\": \"<string>\",\n  \"target\": {\n    \"matchTags\": [\n      [\n        \"<string>\"\n      ]\n    ],\n    \"checkId\": [\n      \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n    ],\n    \"allowDeactivated\": false\n  },\n  \"environmentVariables\": [\n    {\n      \"key\": \"<string>\",\n      \"value\": null,\n      \"secret\": true,\n      \"locked\": false\n    }\n  ],\n  \"retryStrategy\": {\n    \"baseBackoffSeconds\": 60,\n    \"sameRegion\": true,\n    \"onlyOn\": [\n      \"NETWORK_ERROR\"\n    ],\n    \"maxRetries\": 2,\n    \"maxDurationSeconds\": 600\n  },\n  \"refreshCache\": false,\n  \"metadata\": {\n    \"environment\": \"<string>\",\n    \"repoUrl\": \"<string>\",\n    \"commitId\": \"<string>\",\n    \"commitOwner\": \"<string>\",\n    \"commitMessage\": \"<string>\",\n    \"branchName\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

201

{
  "testSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "testSessionLink": "<string>",
  "name": "<string>",
  "errorGroupIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "timeElapsed": 123,
  "stoppedAt": "2023-11-07T05:31:56Z",
  "metadata": {
    "environment": "<string>",
    "repoUrl": "<string>",
    "commitId": "<string>",
    "commitOwner": "<string>",
    "commitMessage": "<string>",
    "branchName": "<string>"
  },
  "results": [
    {
      "testSessionResultId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "testSessionResultLink": "<string>",
      "errorGroupIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "hasErrors": true,
      "hasFailures": true,
      "isDegraded": true,
      "aborted": true,
      "checkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "runLocation": "<string>"
    }
  ]
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

{
  "statusCode": 123,
  "error": "<string>",
  "message": "<string>"
}

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]"

Headers

x-checkly-account · string<uuid>

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Body

application/json

name · string · required

The name of the test session.

Minimum string length: 1

runLocation · string · required

A public region code or private location slug name.

Minimum string length: 1

target · object

Show child attributes

environmentVariables · object[]

Maximum array length: 50

Option 1

Option 2

Show child attributes

retryStrategy · object

Option 1

Option 2

Show child attributes

refreshCache · boolean · default: false

Skip existing caches and install dependencies from scratch.

metadata · object

Show child attributes

Response

201

application/json

Created

testSessionId · string<uuid> · required

testSessionLink · string<uri> · required

name · string · required

status · enum<string> · required

Available options: RUNNING, FAILED, PASSED, CANCELLED

errorGroupIds · string<uuid>[] · required

IDs of the test-session error groups observed in this test session.

startedAt · string<date-time> · required

timeElapsed · number · required

stoppedAt · string<date-time> | null

metadata · object

Show child attributes

results · object[]

Show child attributes