---
title: Metrics API
description: Retrieve detailed performance metrics and aggregated statistics for your monitors via the Cronitor 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. {% .lead %}

## Metrics

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

```bash
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
```bash
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
```bash
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
```bash
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
```bash
curl "https://cronitor.io/api/metrics?monitor=abc123&time=30d&field=success_rate&withNulls=true" \
  -u API_KEY:
```

### Response Format

```json
{
  "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.

```bash
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
```bash
curl "https://cronitor.io/api/aggregates?monitor=abc123&monitor=def456&time=30d" \
  -u API_KEY:
```

#### Get Aggregates for All Monitors in Environment
```bash
curl "https://cronitor.io/api/aggregates?env=production&time=7d" \
  -u API_KEY:
```

#### Get Aggregates for Specific Time Range
```bash
curl "https://cronitor.io/api/aggregates?group=api-services&start=1640995200&end=1641081600" \
  -u API_KEY:
```

### Response Format

```json
{
  "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
```json
{
  "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
```json
{
  "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