# checkly checks - Checkly Docs

> List, inspect, run, and analyze checks in your Checkly account.

Source: https://www.checklyhq.com/docs/cli/checkly-checks/

---

- Usage
- Subcommands
- checkly checks list List Options
- List Examples

- checkly checks run Run Examples

- checkly checks get Get Options
- Get Examples

- checkly checks stats Stats Options
- Stats Examples

- checkly checks delete Delete Options
- Delete Examples

- Related Commands

CLI Commands

# checkly checks

List, inspect, run, and analyze checks in your Checkly account.

Available since CLI v7.3.0. Analytics stats available since v7.6.0.

The `checkly checks` command lets you list, inspect, run, and analyze checks in your Checkly account directly from the terminal. You can filter, search, run deployed checks on demand, and drill into individual check details, recent results, error groups, and analytics stats.

Prerequisites

Before using `checkly checks`, ensure you have:

- Checkly CLI installed

- Valid Checkly account authentication (run `npx checkly login` if needed)

For additional setup information, see [CLI overview](https://www.checklyhq.com/docs/cli/overview).

## ​ Usage

Terminal

```
npx checkly checks [arguments] [options]
```

## ​ Subcommands

Subcommand Description

`list` List all checks in your account.

`get` Get details of a specific check, including recent results and analytics stats.

`run` Run deployed checks now using their configured locations and alerting rules.

`stats` Show analytics stats for your checks.

`delete` Delete a check by ID.

## ​ `checkly checks list`

List all checks in your account with optional filtering by name, tag, check type, or status.
**Usage:**
Terminal

```
npx checkly checks list [options]
```

**Options:**
Option Required Description

`--limit, -l` - Number of checks to return (1-100). Default: `25`.

`--page, -p` - Page number. Default: `1`.

`--search, -s` - Filter checks by name (case-insensitive).

`--tag, -t` - Filter by tag. Can be specified multiple times.

`--type` - Filter by check type.

`--status` - Filter by check status: `passing`, `failing`, or `degraded`.

`--hide-id` - Hide check IDs in table output.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

### ​ List Options

​

number

default: "25"

Number of checks to return per page, between 1 and 100. **Usage:** Terminal

```
npx checkly checks list --limit=50
npx checkly checks list -l 10
```

​

number

default: "1"

Page number for paginated results. **Usage:** Terminal

```
npx checkly checks list --page=2
npx checkly checks list -p 3
```

​

string

Filter checks by name using a case-insensitive search. **Usage:** Terminal

```
npx checkly checks list --search="homepage"
npx checkly checks list -s "api"
```

​

string

Filter checks by tag. Specify multiple times to filter by multiple tags. **Usage:** Terminal

```
npx checkly checks list --tag=production
npx checkly checks list -t production -t critical
```

​

string

Filter checks by type. Available types: `API`, `BROWSER`, `MULTI_STEP`, `HEARTBEAT`, `PLAYWRIGHT`, `TCP`, `DNS`, `ICMP`, `URL`. **Usage:** Terminal

```
npx checkly checks list --type=API
npx checkly checks list --type=BROWSER
```

​

string

Filter checks by current status. Available values: `passing`, `failing`, `degraded`. **Usage:** Terminal

```
npx checkly checks list --status=failing
npx checkly checks list --status=degraded
```

​

boolean

Hide check IDs in table output for a cleaner view. **Usage:** Terminal

```
npx checkly checks list --hide-id
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly checks list --output=json
npx checkly checks list -o md
```

### ​ List Examples

Terminal

```
# List all checks with default settings
npx checkly checks list

# Search for checks by name
npx checkly checks list --search="homepage"

# Filter by tag and type
npx checkly checks list --tag=production --type=API

# Show only failing checks
npx checkly checks list --status=failing

# Get results as JSON
npx checkly checks list --output=json

# Page through results
npx checkly checks list --limit=10 --page=2
```

## ​ `checkly checks run`

The `checkly checks run` command is available since CLI v8.18.0.

Run deployed checks immediately using their configured locations and alerting rules. This is the CLI equivalent of selecting **Schedule now** in the Checkly dashboard.

These are normal monitoring runs. They update check health and can trigger configured alerts. To run checks in a test session without affecting monitoring state or sending alerts, use [`checkly trigger`](https://www.checklyhq.com/docs/cli/checkly-trigger).

**Usage:**
Terminal

```
npx checkly checks run [options]
```

Without a selector, the command runs all eligible checks in your account. By default, it waits up to 600 seconds for every check session to finish and exits with a failing status code if a session fails, times out, or is cancelled.
**Options:**
Option Required Description

`--tags, -t` - Select checks by tag. Use commas to require multiple tags, or repeat the option to match any filter.

`--check-id` - Run specific checks by ID. Accepts comma-separated values and can be repeated.

`--refresh-cache` - Refresh the selected checks cache before running.

`--timeout` - Number of seconds to wait for all check sessions to finish. Default: `600`.

`--detach, -d` - Start the check sessions and exit without waiting for results.

`--[no-]fail-on-no-matching` - Fail when no checks match. Enabled by default.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

### ​ Run Examples

Terminal

```
# Run one deployed check and wait for its result
npx checkly checks run --check-id=

# Run checks that have both the production and api tags
npx checkly checks run --tags=production,api

# Run checks matching either tag filter
npx checkly checks run --tags=production,api --tags=critical

# Schedule matching checks and exit immediately
npx checkly checks run --tags=production --detach

# Return machine-readable results
npx checkly checks run --check-id= --output=json

# Exit successfully when no checks match
npx checkly checks run --tags=optional --no-fail-on-no-matching
```

The `--timeout` option only controls how long the CLI waits. Check sessions continue running in Checkly after the CLI times out. Use `--detach` when you do not need to wait for results.

## ​ `checkly checks get`

Get details of a specific check, including recent results and analytics stats. Use `--result` to drill into a specific result, `--error-group` to view error details, or the stats flags to customize the analytics view.
**Usage:**
Terminal

```
npx checkly checks get [options]
```

**Arguments:**
Argument Description

`id` The ID of the check to retrieve.

**Options:**
Option Required Description

`--result, -r` - Show details for a specific result ID.

`--error-group, -e` - Show full details for a specific error group ID.

`--results-limit` - Number of recent results to show. Default: `10`.

`--results-cursor` - Cursor for results pagination (from previous output).

`--stats-range` - Time range for stats: `last24Hours`, `last7Days`, `last30Days`, `thisWeek`, `thisMonth`, `lastWeek`, `lastMonth`. Default: `last24Hours`.

`--group-by` - Group stats by dimension: `location` or `statusCode`.

`--metrics` - Comma-separated list of metrics to show (overrides defaults).

`--filter-status` - Only include runs with this status in stats: `success` or `failure`.

`--output, -o` - Output format: `detail`, `json`, or `md`. Default: `detail`.

### ​ Get Options

​

string

Drill into a specific check result by its result ID. Shows detailed information including logs and timing data. **Usage:** Terminal

```
npx checkly checks get --result=
npx checkly checks get -r
```

​

string

Show full details for a specific error group, including error messages and affected results. **Usage:** Terminal

```
npx checkly checks get --error-group=
npx checkly checks get -e
```

If your account has [Rocky AI Root Cause Analysis](https://www.checklyhq.com/docs/resolve/ai-root-cause-analysis/overview) enabled, the returned error group details include the AI-generated root cause analysis for that error group.

​

number

default: "10"

Number of recent results to display. **Usage:** Terminal

```
npx checkly checks get --results-limit=20
```

​

string

Cursor for paginating through results. The cursor value is provided in the output of a previous `checks get` command. **Usage:** Terminal

```
npx checkly checks get --results-cursor=
```

​

string

default: "last24Hours"

Time range for the analytics stats section. Available ranges: `last24Hours`, `last7Days`, `last30Days`, `thisWeek`, `thisMonth`, `lastWeek`, `lastMonth`. **Usage:** Terminal

```
npx checkly checks get --stats-range=last7Days
```

​

string

Group analytics stats by a specific dimension. Use `location` to break down metrics by geographic region, or `statusCode` to group by HTTP status code. **Usage:** Terminal

```
npx checkly checks get --group-by=location
npx checkly checks get --group-by=statusCode
```

​

string

Comma-separated list of metrics to display, overriding the defaults. When omitted, a sensible set of defaults is used based on the check type. You can also retrieve the full list of available metrics from the [List all available reporting metrics](https://www.checklyhq.com/docs/api-reference/analytics/list-all-available-reporting-metrics) API endpoint. **Available metrics by check type:** Metric Applies to Unit

`availability` All check types %

`responseTime_avg` API, Browser, Playwright, Multi-Step, URL ms

`responseTime_p50` API, Browser, Playwright, Multi-Step, URL ms

`responseTime_p95` API, Browser, Playwright, Multi-Step, URL ms

`responseTime_p99` API, Browser, Playwright, Multi-Step, URL ms

`total_avg` TCP, DNS ms

`total_p50` TCP, DNS ms

`total_p95` TCP, DNS ms

`total_p99` TCP, DNS ms

`latencyAvg_avg` ICMP ms

`latencyAvg_p50` ICMP ms

`latencyAvg_p95` ICMP ms

`latencyAvg_p99` ICMP ms

`packetLoss_avg` ICMP %

`LCP_avg` Browser, Playwright ms

`CLS_avg` Browser, Playwright score

`TBT_avg` Browser, Playwright ms

**Default metrics per check type:** Check type Default metrics

API, Multi-Step, URL `availability`, `responseTime_avg`, `responseTime_p50`, `responseTime_p95`, `responseTime_p99`

Browser, Playwright `availability`, `LCP_avg`, `CLS_avg`, `TBT_avg`, `responseTime_avg`, `responseTime_p95`

TCP, DNS `availability`, `total_avg`, `total_p50`, `total_p95`, `total_p99`

ICMP `availability`, `packetLoss_avg`, `latencyAvg_avg`, `latencyAvg_p50`, `latencyAvg_p95`, `latencyAvg_p99`

Heartbeat `availability`

**Usage:** Terminal

```
npx checkly checks get --metrics=availability,responseTime_avg,responseTime_p95
```

​

string

Only include runs with a specific status in the analytics stats. Use `success` to see stats for passing runs only, or `failure` for failing runs. **Usage:** Terminal

```
npx checkly checks get --filter-status=failure
npx checkly checks get --filter-status=success
```

​

string

default: "detail"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly checks get --output=json
npx checkly checks get -o md
```

### ​ Get Examples

Terminal

```
# View check details, recent results, and stats
npx checkly checks get 12345

# View stats for the last 7 days
npx checkly checks get 12345 --stats-range=last7Days

# Break down stats by location
npx checkly checks get 12345 --group-by=location

# Show only specific metrics
npx checkly checks get 12345 --metrics=availability,responseTime_avg,responseTime_p95

# Show stats for failed runs only
npx checkly checks get 12345 --filter-status=failure

# Drill into a specific result
npx checkly checks get 12345 --result=abc-123

# View an error group
npx checkly checks get 12345 --error-group=err-456

# Get check details as JSON
npx checkly checks get 12345 --output=json

# Show more results
npx checkly checks get 12345 --results-limit=25
```

## ​ `checkly checks stats`

Show analytics stats for your checks. View availability, response times, and other metrics across multiple checks at once, with filtering by tag, type, or name.
**Usage:**
Terminal

```
npx checkly checks stats [checkIds...] [options]
```

**Arguments:**
Argument Description

`checkIds` One or more check IDs to get stats for. If omitted, stats are shown for all checks.

**Options:**
Option Required Description

`--range, -r` - Time range for stats: `last24Hours`, `last7Days`, `thisWeek`, `lastWeek`, `lastMonth`. Default: `last24Hours`.

`--limit, -l` - Number of checks to return (1-100). Default: `25`.

`--page, -p` - Page number. Default: `1`.

`--search, -s` - Filter checks by name (case-insensitive).

`--tag, -t` - Filter by tag. Can be specified multiple times.

`--type` - Filter by check type.

`--output, -o` - Output format: `table`, `json`, or `md`. Default: `table`.

### ​ Stats Options

​

string

default: "last24Hours"

Time range for the analytics stats. Available ranges: `last24Hours`, `last7Days`, `thisWeek`, `lastWeek`, `lastMonth`. **Usage:** Terminal

```
npx checkly checks stats --range=last7Days
npx checkly checks stats -r lastMonth
```

​

number

default: "25"

Number of checks to return per page, between 1 and 100. **Usage:** Terminal

```
npx checkly checks stats --limit=50
npx checkly checks stats -l 10
```

​

number

default: "1"

Page number for paginated results. **Usage:** Terminal

```
npx checkly checks stats --page=2
npx checkly checks stats -p 3
```

​

string

Filter checks by name using a case-insensitive search. **Usage:** Terminal

```
npx checkly checks stats --search="homepage"
npx checkly checks stats -s "api"
```

​

string

Filter checks by tag. Specify multiple times to filter by multiple tags. **Usage:** Terminal

```
npx checkly checks stats --tag=production
npx checkly checks stats -t production -t critical
```

​

string

Filter checks by type. Available types: `API`, `BROWSER`, `MULTI_STEP`, `HEARTBEAT`, `PLAYWRIGHT`, `TCP`, `DNS`, `ICMP`, `URL`. **Usage:** Terminal

```
npx checkly checks stats --type=API
npx checkly checks stats --type=BROWSER
```

​

string

default: "table"

Set the output format. Use `json` for programmatic access or `md` for markdown. **Usage:** Terminal

```
npx checkly checks stats --output=json
npx checkly checks stats -o md
```

### ​ Stats Examples

Terminal

```
# Show stats for all checks (last 24 hours)
npx checkly checks stats

# Show stats for specific checks
npx checkly checks stats 12345 67890

# Show stats for the last 7 days
npx checkly checks stats --range=last7Days

# Filter by tag and type
npx checkly checks stats --tag=production --type=API

# Search by name and output as JSON
npx checkly checks stats --search="homepage" --output=json

# Page through results
npx checkly checks stats --limit=10 --page=2
```

## ​ `checkly checks delete`

The `checkly checks delete` command is only available since CLI v8.8.0.

Delete a check by ID. By default, the command shows the check to be deleted and prompts for confirmation before proceeding.

Checks managed by a CLI project are recreated on the next `checkly deploy`. To permanently remove a project-managed check, delete it from your project code instead of using this command.

**Usage:**
Terminal

```
npx checkly checks delete [options]
```

**Arguments:**
Argument Description

`id` The ID of the check to delete.

**Options:**
Option Required Description

`--force, -f` - Skip the confirmation prompt.

`--dry-run` - Preview what would happen without deleting the check.

### ​ Delete Options

​

boolean

default: "false"

Skip the confirmation prompt and delete the check immediately. Useful in scripts and CI. **Usage:** Terminal

```
npx checkly checks delete 12345 --force
npx checkly checks delete 12345 -f
```

​

boolean

default: "false"

Preview the deletion without making any changes. Shows the check that would be deleted. **Usage:** Terminal

```
npx checkly checks delete 12345 --dry-run
```

### ​ Delete Examples

Terminal

```
# Delete a check with a confirmation prompt
npx checkly checks delete 12345

# Preview the deletion without making changes
npx checkly checks delete 12345 --dry-run

# Delete without a confirmation prompt
npx checkly checks delete 12345 --force
```

## ​ Related Commands

- [`checkly status-pages`](https://www.checklyhq.com/docs/cli/checkly-status-pages) - List and inspect status pages

- [`checkly trigger`](https://www.checklyhq.com/docs/cli/checkly-trigger) - Run deployed checks in a test session without affecting monitoring state

- [`checkly whoami`](https://www.checklyhq.com/docs/cli/checkly-whoami) - Display current account information

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/cli/checkly-checks.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/checkly-checks)

[checkly assets Previous](https://www.checklyhq.com/docs/cli/checkly-assets)[checkly deploy Next](https://www.checklyhq.com/docs/cli/checkly-deploy)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)