# Usage and Meters API Reference

REST schemas and generated examples for usage submission, batch ingestion, totals, and dimensional breakdowns.

<!-- docs-source -->
Source: https://learning.monetizekit.app/docs/api-reference/usage
<!-- /docs-source -->

Mock API reference used by the interactive docs explorer.

| OpenAPI version | Contract version | REST base path |
| --- | --- | --- |
| 3.1.0 | 2026-03-15 | /api/v1 |

## Servers

| URL | Environment |
| --- | --- |
| `https://app.monetizekit.app/api/v1` | Development environment |
| `https://app.monetizekit.app/api/v1` | Staging environment |
| `https://app.monetizekit.app/api/v1` | Production environment |

## usage operations

### Submit usage event

`POST /usage/events` — Ingests a metered usage event.

Operation ID: usage.submit.

Required scopes: usage:write.

#### Parameters

| Name | In | Required | Description | Schema | Example |
| --- | --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | Client-generated idempotency key | { "type": "string" } | "idem_2f5fd2b7a1" |

#### Request schema

```json
{
  "type": "object",
  "required": [
    "customerId",
    "meterId",
    "value"
  ],
  "properties": {
    "customerId": {
      "type": "string"
    },
    "meterId": {
      "type": "string"
    },
    "value": {
      "type": "number"
    }
  }
}
```

#### Request example

```json
{
  "customerId": "cust_dev_1001",
  "meterId": "api_requests",
  "value": 15,
  "occurredAt": "2026-03-15T12:00:00.000Z"
}
```

#### Responses

`201` — Recorded

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "customerId": {
      "type": "string"
    },
    "meterId": {
      "type": "string"
    },
    "eventName": {
      "type": "string"
    },
    "value": {
      "type": "number"
    },
    "status": {
      "type": "string"
    },
    "occurredAt": {
      "type": "string"
    },
    "createdAt": {
      "type": "string"
    }
  }
}
```

```json
{
  "id": "evt_9012",
  "customerId": "cust_dev_1001",
  "meterId": "api_requests",
  "eventName": "usage.recorded",
  "value": 15,
  "status": "success",
  "occurredAt": "2026-03-15T12:00:00.000Z",
  "createdAt": "2026-03-15T12:00:00.000Z"
}
```

### Submit a batch of usage events

`POST /usage/events/batch` — Ingests up to 500 usage events in one request. Each item carries its own idempotency key, so replaying a window missed during an outage converges without duplicates while preserving each event's original occurredAt. Item-level failures do not fail the batch. Each accepted item names its stored event by eventId; pass ?include=events to receive the full event object per item.

Operation ID: usage.submitBatch.

Required scopes: usage:write.

#### Parameters

| Name | In | Required | Description | Schema | Example |
| --- | --- | --- | --- | --- | --- |
| `include` | query | no | Comma-separated extras to include per result. `events` adds the stored event object (the shape POST /usage/events returns) to every created or duplicate item; omitted by default because a 500-item batch would return roughly 200 KB of copies of the request. | { "type": "string", "enum": [ "events" ] } | "events" |

#### Request schema

```json
{
  "type": "object",
  "required": [
    "events"
  ],
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "customerId",
          "meterId",
          "value",
          "idempotencyKey"
        ],
        "properties": {
          "customerId": {
            "type": "string"
          },
          "meterId": {
            "type": "string"
          },
          "value": {
            "type": "number"
          },
          "idempotencyKey": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### Request example

```json
{
  "events": [
    {
      "customerId": "cust_dev_1001",
      "meterId": "api_requests",
      "value": 15,
      "idempotencyKey": "idem_replay_0001",
      "occurredAt": "2026-03-15T11:00:00.000Z"
    },
    {
      "customerId": "cust_dev_1001",
      "meterId": "api_requests",
      "value": 8,
      "idempotencyKey": "idem_replay_0002",
      "occurredAt": "2026-03-15T11:30:00.000Z"
    }
  ]
}
```

#### Responses

`200` — Batch processed

```json
{
  "type": "object",
  "required": [
    "summary",
    "results"
  ],
  "properties": {
    "summary": {
      "type": "object",
      "required": [
        "total",
        "created",
        "duplicate",
        "errors"
      ],
      "properties": {
        "total": {
          "type": "number"
        },
        "created": {
          "type": "number"
        },
        "duplicate": {
          "type": "number"
        },
        "errors": {
          "type": "number"
        }
      }
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "index",
          "idempotencyKey",
          "status"
        ],
        "properties": {
          "index": {
            "type": "number"
          },
          "idempotencyKey": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "duplicate",
              "error"
            ]
          },
          "eventId": {
            "type": "string",
            "description": "Id of the stored event, on created and duplicate items."
          },
          "event": {
            "type": "object",
            "description": "The stored event, only when the request asked for ?include=events."
          },
          "error": {
            "type": "object",
            "description": "On error items: the same code and message a single-event request would return.",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
```

```json
{
  "summary": {
    "total": 2,
    "created": 1,
    "duplicate": 1,
    "errors": 0
  },
  "results": [
    {
      "index": 0,
      "idempotencyKey": "idem_replay_0001",
      "status": "created",
      "eventId": "evt_9013"
    },
    {
      "index": 1,
      "idempotencyKey": "idem_replay_0002",
      "status": "duplicate",
      "eventId": "evt_9014"
    }
  ]
}
```

### Get usage counter

`GET /usage/{customerId}/{meterId}` — Returns current counter for a customer and meter.

Operation ID: usage.retrieve.

Required scopes: usage:read.

#### Parameters

| Name | In | Required | Description | Schema | Example |
| --- | --- | --- | --- | --- | --- |
| `customerId` | path | yes | Customer ID | { "type": "string" } | "cust_dev_1001" |
| `meterId` | path | yes | Meter key | { "type": "string" } | "api_requests" |

#### Responses

`200` — Success

```json
{
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string"
    },
    "meterId": {
      "type": "string"
    },
    "current": {
      "type": "number"
    },
    "limit": {
      "type": "number"
    }
  }
}
```

```json
{
  "customerId": "cust_dev_1001",
  "meterId": "api_requests",
  "current": 120,
  "limit": 1000
}
```

### Get usage breakdown

`GET /usage/{customerId}/{meterId}/breakdown` — Returns usage grouped by a required dimension.

Operation ID: usage.breakdown.

Required scopes: usage:read.

#### Parameters

| Name | In | Required | Description | Schema | Example |
| --- | --- | --- | --- | --- | --- |
| `customerId` | path | yes | Customer ID | { "type": "string" } | "cust_dev_1001" |
| `meterId` | path | yes | Meter key | { "type": "string" } | "api_requests" |
| `dimension` | query | yes | Dimension to group usage by | { "type": "string" } | "model" |

#### Responses

`200` — Success

```json
{
  "type": "object",
  "properties": {
    "meterId": {
      "type": "string"
    },
    "dimension": {
      "type": "string"
    },
    "window": {
      "type": "string"
    },
    "total": {
      "type": "number"
    },
    "totalCreditCost": {
      "type": "number"
    },
    "breakdown": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string"
          },
          "total": {
            "type": "number"
          },
          "count": {
            "type": "number"
          },
          "creditCost": {
            "type": "number"
          }
        }
      }
    }
  }
}
```

```json
{
  "meterId": "api_requests",
  "dimension": "model",
  "window": "all",
  "total": 120,
  "totalCreditCost": 42,
  "breakdown": [
    {
      "value": "gpt-4.1",
      "total": 120,
      "count": 4,
      "creditCost": 42
    }
  ]
}
```