# Usage, limits and the log

Who pays, usage as records, limits per business, key and customer, and the log of every call.

## Who pays

A business you brought (made for your connection, or a test business) counts on your plan; a project its owner already had keeps its own. Your calls inside a business are always counted on your project, by connection and key.

## Usage as records

`GET /usage/records` answers one meter between two days, cut by day, connection, key or customer. `api_calls` is the calls made with your keys, those inside your businesses included.

Request:

```
curl -sS "https://api.rivier.ai/usage/records?meter=api_calls&from=2026-12-01&to=2026-12-07&by=connection" \
  -H "Authorization: Bearer $RIVIER_API_KEY"
```

## Your own limits

`PUT /usage/allocations` bounds a meter for one connected business, one key or one customer. You hear `usage.threshold` when one nears its end and `usage.limit_reached` when it is full, each naming the `scope`.

Request:

```
curl -sS -X PUT https://api.rivier.ai/usage/allocations \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meter": "bookings", "scopeKind": "connection", "scopeId": "$A", "limit": 500}'
```

## The log of calls

Every call made with a key is a row in `GET /usage/requests` for 30 days: the operation, status, time taken, key, connection, idempotency key and error code, and no bodies. Every answer carries `x-rivier-request-id`; quote it when you ask about a call.

Request:

```
curl -sS "https://api.rivier.ai/usage/requests?status=4xx&connection=$A" \
  -H "Authorization: Bearer $RIVIER_API_KEY"
```

## Limits and refusals

Too many calls answer 429 with `retry-after` in seconds and the class that was full. An allowance that is used up answers `quota_exceeded` with a sentence you can show; it is not worth retrying before the period resets.
