> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# metrics

> Provider-neutral project and database time series for compute, memory, disk, network, process, HTTP, database, queue, and cron health. Raw one-minute data is retained 30 days and hourly aggregates 13 months.

Provider-neutral project and database time series for compute, memory, disk, network, process, HTTP, database, queue, and cron health. Raw one-minute data is retained 30 days and hourly aggregates 13 months.

## metrics.catalog

List every public metric, unit, scope, aggregation, grouping dimension, and retention tier.

```text theme={null}
GET /v1/orgs/{orgId}/metrics/catalog
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/metrics/catalog" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                              |
| ------ | ---------------------------------------- |
| `200`  | Provider-neutral public metrics catalog. |

### Response body (200)

| Field                             | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `retention`                       | object    | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `retention.rawDays`               | integer   | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `retention.hourlyMonths`          | integer   | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics`                         | object\[] | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].name`                  | string    | One of: `cpu.percent`, `memory.used_bytes`, `memory.limit_bytes`, `disk.used_bytes`, `disk.limit_bytes`, `disk.read_iops`, `disk.write_iops`, `network.receive_bytes`, `network.transmit_bytes`, `runtime.restarts`, `runtime.uptime_seconds`, `http.requests`, `http.errors`, `database.connections`, `database.pool_waiting`, `database.queries_per_second`, `database.query_latency_avg_ms`, `database.query_latency_p50_ms`, `database.query_latency_p90_ms`, `database.query_latency_p95_ms`, `database.query_latency_p99_ms`, `queue.backlog_messages`, `queue.oldest_message_age_seconds`, `cron.failures`. |
| `metrics[].label`                 | string    | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].description`           | string    | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].unit`                  | string    | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].category`              | string    | One of: `compute`, `memory`, `storage`, `network`, `http`, `database`, `queue`, `cron`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `metrics[].scopes`                | string\[] | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].defaultAggregation`    | string    | One of: `avg`, `min`, `max`, `sum`, `p50`, `p95`, `p99`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `metrics[].supportedAggregations` | string\[] | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `metrics[].groupBy`               | string\[] | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## metrics.queryProject

Query bounded project runtime and application metric series through the Korve control plane.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/metrics/query
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Query parameters

| Name          | Type   | Required | Description                        |
| ------------- | ------ | -------- | ---------------------------------- |
| `environment` | string | No       | Pattern: `^[a-z][a-z0-9-]{0,38}$`. |

### Request body

| Field         | Type      | Required | Description                                                                                 |
| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `names`       | string\[] | Yes      | One to 10 metric names.                                                                     |
| `from`        | string    | Yes      | Format: `date-time`.                                                                        |
| `until`       | string    | Yes      | Format: `date-time`.                                                                        |
| `stepSeconds` | integer   | No       | Bucket width. Raw one-minute data is retained for 30 days; hourly aggregates for 13 months. |
| `aggregation` | string    | No       | One of: `avg`, `min`, `max`, `sum`, `p50`, `p95`, `p99`.                                    |
| `groupBy`     | string\[] | No       | —                                                                                           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/metrics/query?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "cpu.percent"
  ],
  "from": "2026-06-01T12:00:00Z",
  "until": "2026-06-01T12:00:00Z"
}'
```

### Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `200`  | Metric series in ascending timestamp order.                  |
| `404`  | No such project or environment.                              |
| `422`  | Invalid metric, time window, step, aggregation, or grouping. |
| `429`  | Metrics query limit reached.                                 |

### Response body (200)

| Field                         | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from`                        | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `until`                       | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `stepSeconds`                 | integer        | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series`                      | object\[]      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].name`               | string         | One of: `cpu.percent`, `memory.used_bytes`, `memory.limit_bytes`, `disk.used_bytes`, `disk.limit_bytes`, `disk.read_iops`, `disk.write_iops`, `network.receive_bytes`, `network.transmit_bytes`, `runtime.restarts`, `runtime.uptime_seconds`, `http.requests`, `http.errors`, `database.connections`, `database.pool_waiting`, `database.queries_per_second`, `database.query_latency_avg_ms`, `database.query_latency_p50_ms`, `database.query_latency_p90_ms`, `database.query_latency_p95_ms`, `database.query_latency_p99_ms`, `queue.backlog_messages`, `queue.oldest_message_age_seconds`, `cron.failures`. |
| `series[].unit`               | string         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].labels`             | object         | Map of string values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `series[].points`             | object\[]      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].points[].timestamp` | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `series[].points[].value`     | number or null | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## metrics.queryDatabase

Query bounded database compute, storage, connection, pool, and query-throughput series.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/databases/{databaseId}/metrics/query
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Request body

| Field         | Type      | Required | Description                                                                                 |
| ------------- | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `names`       | string\[] | Yes      | One to 10 metric names.                                                                     |
| `from`        | string    | Yes      | Format: `date-time`.                                                                        |
| `until`       | string    | Yes      | Format: `date-time`.                                                                        |
| `stepSeconds` | integer   | No       | Bucket width. Raw one-minute data is retained for 30 days; hourly aggregates for 13 months. |
| `aggregation` | string    | No       | One of: `avg`, `min`, `max`, `sum`, `p50`, `p95`, `p99`.                                    |
| `groupBy`     | string\[] | No       | —                                                                                           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/databases/$DATABASE_ID/metrics/query" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "cpu.percent"
  ],
  "from": "2026-06-01T12:00:00Z",
  "until": "2026-06-01T12:00:00Z"
}'
```

### Responses

| Status | Description                                                           |
| ------ | --------------------------------------------------------------------- |
| `200`  | Database metric series in ascending timestamp order.                  |
| `404`  | No such database in this project.                                     |
| `422`  | Invalid database metric, time window, step, aggregation, or grouping. |
| `429`  | Metrics query limit reached.                                          |

### Response body (200)

| Field                         | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from`                        | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `until`                       | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `stepSeconds`                 | integer        | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series`                      | object\[]      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].name`               | string         | One of: `cpu.percent`, `memory.used_bytes`, `memory.limit_bytes`, `disk.used_bytes`, `disk.limit_bytes`, `disk.read_iops`, `disk.write_iops`, `network.receive_bytes`, `network.transmit_bytes`, `runtime.restarts`, `runtime.uptime_seconds`, `http.requests`, `http.errors`, `database.connections`, `database.pool_waiting`, `database.queries_per_second`, `database.query_latency_avg_ms`, `database.query_latency_p50_ms`, `database.query_latency_p90_ms`, `database.query_latency_p95_ms`, `database.query_latency_p99_ms`, `queue.backlog_messages`, `queue.oldest_message_age_seconds`, `cron.failures`. |
| `series[].unit`               | string         | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].labels`             | object         | Map of string values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `series[].points`             | object\[]      | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `series[].points[].timestamp` | string         | Format: `date-time`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `series[].points[].value`     | number or null | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |