Metrics API

The Metrics API provides access to detailed performance data and aggregated statistics for your monitors. Use these endpoints to analyze monitor performance, build custom dashboards, and integrate monitoring data into your applications.

Metrics

Retrieve detailed time-series metrics data for your monitors, including performance statistics, success rates, and execution counts.

GET https://cronitor.io/api/metrics   |   status_codes: 200, 400, 404

Authentication: Requires API key with monitor:read scope or valid session token.

Important: You must specify at least one field parameter to retrieve metrics data. Without specifying which fields to return, the API will not return any metric values.

Query Parameters

Parameter	Type	Description
`monitor`	array	Monitor keys to include
`group`	array	Group keys to include all monitors in groups
`tag`	array	Tag names to include all monitors with tags
`type`	array	Monitor types: `job`, `heartbeat`, `check`, `site`
`time`	string	Named time range: `24h`, `3d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `today`, `yesterday`
`start`	integer	Unix timestamp for custom start time
`end`	integer	Unix timestamp for custom end time
`env`	string	Environment key to filter by
`region`	array	Check regions to include: `all`, `us`, `eu`, `ap`, `sa`, `me`
`field`	array	Required. Specific metric fields to return
`withNulls`	boolean	Include null values for missing data points

Available Metric Fields

Category	Fields
Performance	`duration_p10`, `duration_p50`, `duration_p90`, `duration_p95`, `duration_p99`, `duration_mean`, `success_rate`
Counts	`run_count`, `complete_count`, `fail_count`, `tick_count`, `checks_healthy_count`, `checks_triggered_count`, `checks_failed_count`, `alert_count`
Additional	`length_p10`, `length_p50`, `length_p90`, `length_p95`, `length_p99`, `count_p10`, `count_p50`, `count_p90`, `count_p95`, `count_p99`, `error_count_p10`, `error_count_p50`, `error_count_p90`, `error_count_p95`, `error_count_p99`

Examples

Get Metrics for Specific Monitors

curl "https://cronitor.io/api/metrics?monitor=abc123&monitor=def456&time=24h&field=run_count&field=fail_count" \
  -u API_KEY:

Get Duration Metrics for All Monitors in a Group

curl "https://cronitor.io/api/metrics?group=web-services&field=duration_p50&field=duration_p90&time=7d" \
  -u API_KEY:

Get Custom Time Range with Success Rate

curl "https://cronitor.io/api/metrics?monitor=abc123&start=1640995200&end=1641081600&field=success_rate" \
  -u API_KEY:

Get All Available Metrics with Null Values

curl "https://cronitor.io/api/metrics?monitor=abc123&time=30d&field=success_rate&withNulls=true" \
  -u API_KEY:

Response Format

{
  "monitors": {
    "abc123": {
      "env:production": [
        {
          "stamp": 1640995200,
          "duration_p50": 1250,
          "duration_p90": 2100,
          "success_rate": 98.5,
          "run_count": 24,
          "complete_count": 23,
          "fail_count": 1
        }
      ]
    }
  }
}

Response Fields

monitors - Object containing metrics data keyed by monitor key
stamp - Unix timestamp for the data point
Metric fields - Values for requested metric fields
Dimensions - Data is grouped by environment and region (e.g., env:production, region:us-east-1)

Aggregates

Retrieve aggregated statistics that summarize monitor performance over a time period. This endpoint provides rolled-up metrics without time-series data points.

GET https://cronitor.io/api/aggregates   |   status_codes: 200, 400, 404

Authentication: Requires API key with monitor:read scope or valid session token.

Query Parameters

Parameter	Type	Description
`monitor`	array	Monitor keys to include
`group`	array	Group keys to include all monitors in groups
`tag`	array	Tag names to include all monitors with tags
`type`	array	Monitor types: `job`, `heartbeat`, `check`, `site`
`time`	string	Named time range, as for metrics
`start`	integer	Unix timestamp for custom start time
`end`	integer	Unix timestamp for custom end time
`env`	string	Environment key to filter by
`region`	array	Check regions to include: `all`, `us`, `eu`, `ap`, `sa`, `me`

Examples

Get Aggregated Stats for Multiple Monitors

curl "https://cronitor.io/api/aggregates?monitor=abc123&monitor=def456&time=30d" \
  -u API_KEY:

Get Aggregates for All Monitors in Environment

curl "https://cronitor.io/api/aggregates?env=production&time=7d" \
  -u API_KEY:

Get Aggregates for Specific Time Range

curl "https://cronitor.io/api/aggregates?group=api-services&start=1640995200&end=1641081600" \
  -u API_KEY:

Response Format

{
  "monitors": {
    "abc123": {
      "env:production": {
        "run_count": 720,
        "complete_count": 707,
        "fail_count": 13,
        "tick_count": 0,
        "alert_count": 4,
        "event_count": 720,
        "duration_mean": 1450.5,
        "downtime_seconds": 0,
        "uptime": null
      }
    }
  }
}

Response Fields

monitors - Object containing aggregate data keyed by monitor key, then by dimension (env:<key> for jobs and heartbeats, region:<key> for checks)
run_count, complete_count, fail_count - Job executions started, completed, and failed
tick_count - Heartbeat pings received
alert_count - Alerts sent
event_count - Total events observed across all types
duration_mean - Average execution duration, weighted by event count
downtime_seconds, uptime - For checks, seconds of downtime and the resulting uptime ratio between 0 and 1; null for other monitor types

Aggregates do not include duration percentiles. Request duration_p50 and similar fields from the Metrics endpoint for the same range instead.

Error Responses

400 Bad Request

{
  "error": {
    "message": "Invalid request, see full response for more details",
    "start": "the span between start and end timestamps must be between 3600 and 31536000 seconds"
  }
}

404 Not Found

{
  "error": "No monitors found"
}

Limits

Time range: the span between start and end must be between 1 hour and 1 year

Notes

Metrics data is available at hourly resolution for recent data and daily resolution for historical data
The withNulls parameter is useful for creating consistent time-series visualizations
Regional data is automatically included from all regions unless specifically filtered
Custom metric fields depend on the monitor type and configuration