> ## 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.

# Usage

> Metered usage per project. Internal meters and agents report quantities against rate-card meter ids; reads aggregate the current calendar month.

Metered usage per project. Internal meters and agents report quantities against rate-card meter ids; reads aggregate the current calendar month.

## usage.record

Record a usage quantity against a rate-card meter.

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

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

### Request body

| Field      | Type   | Required | Description                                |
| ---------- | ------ | -------- | ------------------------------------------ |
| `meterId`  | string | Yes      | A known rate-card meter id.                |
| `quantity` | number | Yes      | Quantity in the meter's unit. Must be > 0. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/usage" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meterId": "network.egress",
  "quantity": 2.5
}'
```

### Responses

| Status | Description                                                    |
| ------ | -------------------------------------------------------------- |
| `202`  | Usage recorded. Includes budget standing when a budget exists. |
| `404`  | No such project in this organization.                          |
| `422`  | Unknown meter id or invalid quantity.                          |

### Response body (202)

| Field             | Type    | Description                                                |
| ----------------- | ------- | ---------------------------------------------------------- |
| `ok`              | boolean | —                                                          |
| `budget`          | object  | Present when the project has a budget configured.          |
| `budget.capUsd`   | number  | —                                                          |
| `budget.spendUsd` | number  | —                                                          |
| `budget.exceeded` | boolean | True once month-to-date spend has reached the monthly cap. |

## usage.get

Aggregated usage and cost per meter, current calendar month by default.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/usage
```

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

### Query parameters

| Name          | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `since`       | string | No       | Format: `date-time`. |
| `until`       | string | No       | Format: `date-time`. |
| `granularity` | string | No       | One of: `day`.       |

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/usage?since=2026-06-01T12%3A00%3A00Z" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                                          |
| ------ | -------------------------------------------------------------------- |
| `200`  | Aggregated meters at rate-card prices.                               |
| `404`  | No such project in this organization.                                |
| `422`  | Invalid since/until timestamp, empty window, or invalid granularity. |

### Response body (200)

| Field                     | Type      | Description                                                                                                       |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `meters`                  | object\[] | —                                                                                                                 |
| `meters[].meterId`        | string    | —                                                                                                                 |
| `meters[].quantity`       | number    | —                                                                                                                 |
| `meters[].costUsd`        | number    | —                                                                                                                 |
| `totalUsd`                | number    | —                                                                                                                 |
| `days`                    | object\[] | Present with granularity=day: cost per UTC calendar day, ascending. Days in the window without usage are omitted. |
| `days[].date`             | string    | UTC calendar day, "YYYY-MM-DD".                                                                                   |
| `days[].totalUsd`         | number    | —                                                                                                                 |
| `days[].meters`           | object\[] | That day's cost per meter, ascending by meter id.                                                                 |
| `days[].meters[].meterId` | string    | —                                                                                                                 |
| `days[].meters[].costUsd` | number    | —                                                                                                                 |