---
title: Metering
path: reference/api/metering
status: published
---

# Metering

**6 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`GET /api/v1/internal/quotas/{tenant_id}/{service_slug}/{metric_slug}`](#get-api-v1-internal-quotas-tenant-id-service-slug-metric-slug) — Internal Quota Check
- [`POST /api/v1/metering/events`](#post-api-v1-metering-events) — Post Usage Events
- [`GET /api/v1/usage/by-service/{slug}`](#get-api-v1-usage-by-service-slug) — Get Usage By Service
- [`GET /api/v1/usage/history`](#get-api-v1-usage-history) — Get Usage History
- [`GET /api/v1/usage/quotas`](#get-api-v1-usage-quotas) — Get Usage Quotas
- [`GET /api/v1/usage/summary`](#get-api-v1-usage-summary) — Get Usage Summary

---

### GET `/api/v1/internal/quotas/{tenant_id}/{service_slug}/{metric_slug}` — Internal Quota Check {#get-api-v1-internal-quotas-tenant-id-service-slug-metric-slug}

Internal API for services to check a tenant's quota status before processing.

Requires service account authentication.

**Parameters**:

- `tenant_id` (path, string, required)
- `service_slug` (path, string, required)
- `metric_slug` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_QuotaStatusResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/metering/events` — Post Usage Events {#post-api-v1-metering-events}

Ingest usage events from a service account.

Service accounts authenticate via their ScaiKey service token and push
usage events in batches. Idempotency is enforced via idempotency_key.

**Parameters**:

- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Body**: `UsageEventsRequest` — {`events`}


**Responses**:

- `202` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/usage/by-service/{slug}` — Get Usage By Service {#get-api-v1-usage-by-service-slug}

Detailed usage metrics for a specific service in the current period.

**Parameters**:

- `slug` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_UsageByServiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/usage/history` — Get Usage History {#get-api-v1-usage-history}

Historical usage data across billing periods.

**Parameters**:

- `period_type` (query, string, optional)
- `service_slug` (query, string, optional)
- `limit` (query, integer, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_UsageHistoryEntry__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/usage/quotas` — Get Usage Quotas {#get-api-v1-usage-quotas}

Quota status for all metered metrics across all subscribed services.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_QuotaStatusResponse__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/usage/summary` — Get Usage Summary {#get-api-v1-usage-summary}

Current billing period usage summary for the authenticated tenant.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_UsageSummaryResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}