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: Pass field for built-in rollups, metric for one custom series, or metricNames=true to list names. metric cannot be combined with field or metricNames. Without time, start, or end, the range defaults to the last hour.

Query Parameters

Multiple fields can be requested with field=run_count,fail_count or field=run_count&field=fail_count. You can also combine both formats. Whitespace around each field name is trimmed, and duplicate fields are returned once. Unsupported field names and empty entries (for example, field=run_count,) return 400 Bad Request with details in error.field.

Available Metric Fields

Custom metrics

Pass metric=queue_depth to read one named custom metric as a bucketed series. Each point has avg (the mean of samples in that hour or day) and count (the number of events that carried the name). Explicit zeros are included. Events that omit the name are excluded. Buckets with no samples are omitted unless withNulls=true, which inserts null avg and count — never zeros.

Pass metricNames=true to discover names instead of a series. Discovery is per monitor and environment, ordered by last seen, limited to 100 names. See Custom Metrics.

MCP get_metrics uses the same data path with different parameter names (fields, metric, metric_names) and requires exactly one of those three.

The Aggregates endpoint returns built-in rollups only. Use field there; use the Metrics endpoint for custom series and name discovery.

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 Multiple Metrics with a Comma-Separated List

curl "https://cronitor.io/api/metrics?monitor=abc123&time=7d&field=duration_p50,duration_p99,run_count,fail_count" \
  -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 a Custom Metric Series

curl "https://cronitor.io/api/metrics?monitor=queue-worker&time=24h&metric=queue_depth" \
  -u API_KEY:

Discover Custom Metric Names

curl "https://cronitor.io/api/metrics?monitor=queue-worker&time=7d&metricNames=true" \
  -u API_KEY:

Get Rollups 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": {
      "production": [
        {
          "stamp": 1640995200,
          "duration_p50": 1250,
          "duration_p90": 2100,
          "success_rate": 98.5,
          "run_count": 24,
          "complete_count": 23,
          "fail_count": 1
        }
      ]
    }
  }
}

Custom metric series use the same envelope with avg and count instead of field keys:

{
  "monitors": {
    "queue-worker": {
      "production": [
        {"stamp": 1640995200, "avg": 142.0, "count": 12}
      ]
    }
  }
}

Name discovery returns metric_names instead of monitors:

{
  "metric_names": {
    "queue-worker": {
      "production": ["quality_score", "queue_depth"]
    }
  }
}

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
• avg, count - Custom metric bucket mean and sample count
• Dimensions - Jobs and heartbeats are keyed by environment key (e.g. production). Checks are keyed by region (e.g. us)

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

Examples

Get Aggregated Stats for Multiple Monitors

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

Get Aggregates for All Monitors in Environment

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

Get Aggregates for Specific Time Range

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

Response Format

{
  "monitors": {
    "abc123": {
      "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 environment key for jobs and heartbeats or 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 or custom metric series. Request duration_p50 from the Metrics endpoint, or metric=queue_depth for a named custom series.

Error Responses

400 Bad Request

An unsupported metric field returns a field-specific validation error:

{
  "error": {
    "message": "Invalid request, see full response for more details",
    "field": "Invalid metric field: not_a_metric"
  }
}

Other invalid parameters return details under the corresponding parameter name:

{
  "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. Custom metric gaps are nulls, never zeros
• Regional data is automatically included from all regions unless specifically filtered
• GET /api/monitors/:key includes metric_names for the current environment over the last 7 days. latest_event.metrics is present when status is included (the default) and contains custom names and explicit zeros