Skip to main content
Available since CLI v8.3.0.
This command is primarily designed for agentic workflows — when you need to interact with the Checkly API but a dedicated CLI command doesn’t exist yet for that operation. Make sure your Checkly skills are up to date so your AI agent has the context it needs to use this command effectively.
The checkly api command makes authenticated HTTP requests to the Checkly API. It handles authentication automatically using your current login credentials, so you can query or update your account without manually managing API keys in request headers. For available endpoints, refer to the API reference or the OpenAPI spec.
Before using checkly api, ensure you have:
  • Checkly CLI installed
  • Valid Checkly account authentication (run npx checkly login if needed)
See the Authentication section for other authentication options.

​
Usage

The basic command takes an API endpoint path and optional flags.
Terminal
npx checkly api <endpoint> [options]

​
Arguments

The command takes a single required argument.
ArgumentDescription
ENDPOINTAPI endpoint path, e.g. /v1/checks.

​
Options

All flags are optional.
OptionDescription
-X, --methodHTTP method: GET, POST, PUT, PATCH, or DELETE. Defaults to GET, or POST when fields are present.
-F, --fieldAdd a field as key=value (string) or key:=value (JSON-parsed). Sent as a query parameter for GET requests and in the request body otherwise. Can be used multiple times.
-H, --headerAdd a custom HTTP header as "Key: Value". Can be used multiple times.
--inputRead the request body from a file path, or - to read from stdin.
--jqFilter JSON output using a jq expression. Requires jq to be installed.
-i, --includeInclude HTTP status line and response headers in the output.
--verbosePrint request and response headers to stderr.

​
Examples

​
List all checks

Returns all checks in your account as JSON.
Terminal
npx checkly api /v1/checks

​
Extract specific fields with jq

Use --jq to filter or reshape the JSON response inline.
--jq requires jq to be installed on your system.
Terminal
npx checkly api /v1/checks --jq '.[].name'

"My first check"
"Homepage availability"
"Login flow"

​
Paginate results

Use -F to pass query parameters. The API returns 10 results per page by default. Set -X GET explicitly, since the command otherwise switches to POST when fields are present.
Terminal
# Get the first 5 checks
npx checkly api /v1/checks -X GET -F limit=5

# Get the second page
npx checkly api /v1/checks -X GET -F limit=5 -F page=2

​
Get a single resource

Append the resource ID to the endpoint path to fetch a specific item.
Terminal
npx checkly api /v1/checks/<check-id>

​
List alert channels

Use --jq to extract only the fields you need from the response.
Terminal
npx checkly api /v1/alert-channels --jq '[.[] | {id, type}]'

[
  { "id": 263584, "type": "SMS" },
  { "id": 263585, "type": "EMAIL" },
  { "id": 263586, "type": "SLACK" }
]

​
Update a resource via stdin

Pipe JSON directly into the command using --input -:
Terminal
echo '{"activated": false}' | npx checkly api /v1/checks/<check-id> -X PUT --input -
Or read from a file:
Terminal
npx checkly api /v1/checks/<check-id> -X PUT --input ./payload.json

​
Add custom request headers

Use -H to pass additional HTTP headers with the request. You can repeat the flag for multiple headers.
Terminal
npx checkly api /v1/checks -H "Accept: application/json" -H "X-Custom-Header: value"

​
Inspect response headers

Use -i to include the HTTP status and headers in the output:
Terminal
npx checkly api /v1/checks -i

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
content-range: 0-9/11
...
The content-range header tells you the total number of results (0-9/11 means items 0–9 of 11 total).

​
Debug a request

Use --verbose to print request and response headers to stderr:
Terminal
npx checkly api /v1/checks --verbose

> GET /v1/checks

< 200 OK
< content-type: application/json; charset=utf-8
< content-range: 0-9/11
...
These commands are commonly used alongside checkly api.

​
API Reference

For available endpoints, see the Checkly API reference.