List Check Alerts

Overview

This endpoint returns all alerts that have been triggered by checks in your account. Check alerts are generated when checks fail, recover, or meet specific conditions defined in your alert configurations.

Response Example

{
  "data": [
    {
      "id": "alert_789123456",
      "checkId": "check_api_health",
      "checkName": "Production API Health Check",
      "checkType": "api",
      "alertType": "check_failure",
      "severity": "high",
      "status": "triggered",
      "message": "Check failed: HTTP 500 Internal Server Error",
      "triggeredAt": "2024-01-25T14:30:00.000Z",
      "resolvedAt": null,
      "duration": null,
      "location": {
        "id": "us-east-1",
        "name": "N. Virginia, USA"
      },
      "checkResult": {
        "id": "result_123456789",
        "responseTime": 5240,
        "statusCode": 500,
        "error": "Internal Server Error",
        "url": "https://api.production.com/health"
      },
      "alertChannel": {
        "id": "channel_email_prod",
        "name": "Production Team Email",
        "type": "email"
      },
      "escalationLevel": 1,
      "acknowledgedBy": null,
      "acknowledgedAt": null,
      "tags": ["api", "production", "critical"]
    },
    {
      "id": "alert_987654321",
      "checkId": "check_website_home",
      "checkName": "Homepage Browser Check",
      "checkType": "browser",
      "alertType": "check_recovery",
      "severity": "medium",
      "status": "resolved",
      "message": "Check recovered: Page load successful",
      "triggeredAt": "2024-01-25T13:15:00.000Z",
      "resolvedAt": "2024-01-25T13:17:30.000Z",
      "duration": 150000,
      "location": {
        "id": "eu-west-1",
        "name": "Ireland, Europe"
      },
      "checkResult": {
        "id": "result_987654321",
        "responseTime": 1850,
        "statusCode": 200,
        "pageLoadTime": 2.3,
        "url": "https://www.example.com"
      },
      "alertChannel": {
        "id": "channel_slack_dev",
        "name": "Development Team Slack",
        "type": "slack"
      },
      "escalationLevel": 0,
      "acknowledgedBy": {
        "id": "user_123",
        "name": "John Developer",
        "email": "john@example.com"
      },
      "acknowledgedAt": "2024-01-25T13:16:00.000Z",
      "tags": ["frontend", "homepage"]
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 15,
    "totalItems": 147,
    "limit": 10,
    "hasMore": true
  }
}

Common Use Cases

Incident Response

Monitor and respond to active incidents in real-time

GET /v1/check-alerts?status=triggered&severity=high

SLA Monitoring

Track service level agreement compliance and uptime

GET /v1/check-alerts?period=30d&status=resolved

Performance Analysis

Analyze system performance trends and degradation patterns

GET /v1/check-alerts?alertType=performance_degradation

Alert Management

Manage alert lifecycle and team coordination

GET /v1/check-alerts?acknowledgedBy=null&severity=critical

Query Parameters

Filtering Options

checkId (string): Filter alerts for a specific check
checkType (string): Filter by check type (api, browser, heartbeat, tcp, multistep)
alertType (string): Filter by alert type (check_failure, check_recovery, performance_degradation)
severity (string): Filter by severity level (low, medium, high, critical)
status (string): Filter by alert status (triggered, acknowledged, resolved)
location (string): Filter by monitoring location

Example:

?checkType=api&severity=high&status=triggered&limit=20

Time Range Filters

from (string): Start date for alerts (ISO 8601 format)
to (string): End date for alerts (ISO 8601 format)
period (string): Predefined time period (24h, 7d, 30d)

Example:

?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z

Pagination

page (integer): Page number (default: 1)
limit (integer): Number of alerts per page (default: 10, max: 100)
sortBy (string): Sort field (triggeredAt, severity, duration)
sortOrder (string): Sort order (asc, desc, default: desc)

Default: Returns first 10 alerts sorted by most recent

Alert Types

Check Failure

Triggered when:

HTTP status codes indicate failure (4xx, 5xx)
Network timeouts or connection errors
Browser check script failures
Assertion failures in API checks

Common scenarios:

API endpoints returning 500 errors
Website pages failing to load
Database connection timeouts

Check Recovery

Triggered when:

Previously failing check returns to success
Performance returns to acceptable levels
Services come back online

Indicates:

System has self-recovered
Manual intervention was successful
Temporary issues have resolved

Performance Degradation

Triggered when:

Response times exceed thresholds
Success rates drop below limits
Core Web Vitals degrade

Examples:

API response time > 2 seconds
Page load time > 5 seconds
Success rate < 95%

Heartbeat Missing

Triggered when:

Expected heartbeat signals not received
Service health checks fail
Cron jobs or scheduled tasks miss

Indicates:

Service may be down
Scheduled process failed
Network connectivity issues

Alert Severity Levels

Critical Alerts

Characteristics:

Immediate attention required
Service completely unavailable
Business-critical functionality affected
Customer-facing impact

Examples:

Payment processing API down
Login system failure
Complete website outage
Database connectivity lost

High Severity

Characteristics:

Significant service degradation
Major functionality impacted
Customer experience affected
SLA potentially breached

Examples:

Search functionality slow
File upload failures
Partial API outages
Major performance degradation

Medium Severity

Characteristics:

Minor service degradation
Non-critical features affected
Backup systems available
Limited customer impact

Examples:

Slow loading times
Non-essential API errors
Secondary feature failures
Performance warnings

Low Severity

Characteristics:

Minimal impact
Information or warnings
Proactive notifications
Future potential issues

Examples:

SSL certificate expiring soon
Cache hit rate declining
Non-critical service restarts
Performance trending concerns

Use Cases

Incident Response

Monitor and respond to active incidents:

Get real-time alerts for failing checks
Track alert resolution times
Identify patterns in alert frequency
Coordinate team response efforts

SLA Monitoring

Track service level agreement compliance:

Monitor uptime and availability alerts
Calculate MTTR (Mean Time To Recovery)
Generate SLA compliance reports
Identify SLA breach patterns

Performance Analysis

Analyze system performance trends:

Track performance degradation alerts
Identify recurring performance issues
Monitor seasonal performance patterns
Optimize based on alert frequency

Alert Management

Manage alert lifecycle and team coordination:

Acknowledge alerts to prevent duplicates
Track who is handling incidents
Monitor alert resolution times
Optimize alert configurations

Additional Examples

curl -X GET "https://api.checklyhq.com/v1/check-alerts?status=triggered&severity=high&limit=20" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

Check alerts provide real-time visibility into the health and performance of your monitored services. Use this endpoint to build incident response dashboards and automated alert management systems.

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

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

Query Parameters

limit

integer

default:10

Limit the number of results

Required range: 1 <= x <= 100

page

number

default:1

Page number

from

string<date>

Select documents up from this UNIX timestamp (>= date). Defaults to now - 6 hours.

string<date>

Optional. Select alerts up to this UNIX timestamp (< date). Defaults to 6 hours after "from".

Response

Successful

name

string

required

The name of the check.

Example:

"API Check"

string

The unique ID of this alert.

Example:

"1"

checkId

string

The ID of check this alert belongs to.

Example:

"db147a95-6ed6-44c9-a584-c5dca2db3aaa"

alertType

enum<string>

The type of alert.

Available options:

NO_ALERT,

ALERT_FAILURE,

ALERT_FAILURE_REMAIN,

ALERT_FAILURE_DEGRADED,

ALERT_RECOVERY,

ALERT_DEGRADED,

ALERT_DEGRADED_REMAIN,

ALERT_DEGRADED_FAILURE,

ALERT_DEGRADED_RECOVERY,

ALERT_SSL

Example:

"ALERT_FAILURE"

checkType

enum<string>

The type of the check.

Available options:

API,

BROWSER,

HEARTBEAT,

MULTI_STEP,

TCP,

PLAYWRIGHT,

URL

Example:

"API"

runLocation

string

What data center location this check alert was triggered from.

Example:

"us-east-1"

responseTime

number

Describes the time it took to execute relevant parts of this check. Any setup timeor system time needed to start executing this check in the Checkly backend is not part of this.

Example:

10

error

string

Any specific error messages that were part of the failing check triggering the alert.

Example:

"OK"

statusCode

string

The status code of the response. Only applies to API checks.

Example:

"200"

created_at

string<date>

The date and time this check alert was created.

startedAt

string<date>

The date and time this check alert was started.

Platform

Detect

Communicate

Resolve

Overview

Response Example

Common Use Cases

Incident Response

SLA Monitoring

Performance Analysis

Alert Management

Query Parameters

Alert Types

Check Failure

Check Recovery

Performance Degradation

Heartbeat Missing

Alert Severity Levels

Use Cases

Additional Examples

Authorizations

Headers

Query Parameters

Response

Platform

Detect

Communicate

Resolve

​Overview

​Response Example

​Common Use Cases

Incident Response

SLA Monitoring

Performance Analysis

Alert Management

​Query Parameters

​Alert Types

Check Failure

Check Recovery

Performance Degradation

Heartbeat Missing

​Alert Severity Levels

​Use Cases

​Additional Examples

Authorizations

Headers

Query Parameters

Response

Overview

Response Example

Common Use Cases

Query Parameters

Alert Types

Alert Severity Levels

Use Cases

Additional Examples