# Usage and limits

Plan, usage, limits, allocations, trial and top-ups.

Scopes for this area: `usage:read`, `usage:write` and `usage:admin`.

20 operations.

## key

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/keys/usage` | Requests and tokens per key per day. | read | `rivier usage key usage` |

## plan

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage` | Usage against the plan, by meter. | read | `rivier usage plan report` |
| GET | `/usage/can` | Whether a capability is allowed now, and why not. | read | `rivier usage plan can` |

## trial

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/trial` | Trial status. | read | `rivier usage trial get` |

## allocation

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/allocations` | Allowances set for products, agents and channels. | read | `rivier usage allocation list` |
| PUT | `/usage/allocations` | Set an allowance. | admin | `rivier usage allocation set` |
| DELETE | `/usage/allocations` | Remove an allowance. | admin | `rivier usage allocation remove` |

## overage

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| PUT | `/usage/overage` | Allow a meter to run past its included amount. | admin | `rivier usage overage set` |

## topup

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/usage/topups` | Add a top-up. | admin | `rivier usage topup create` |

## warning

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| PUT | `/usage/warn` | Set the warning threshold. | admin | `rivier usage warning set` |

## project

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/projects` | The projects you own, by name. A key sees the one project it belongs to. | read | `rivier usage project list` |

## limit

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/limits` | Every allowance of the project this period: included, used, what is left, when it resets, the project's choice at the limit, and whether the organisation pools it. | read | `rivier usage limit list` |
| POST | `/usage/limits/check` | Whether a send or call of this size fits right now, without using anything. When it does not, the plain reason and the next step. Ask before a large send. | read | `rivier usage limit check` |
| GET | `/usage/limits/{meter}` | One allowance in full. | read | `rivier usage limit get` |
| PUT | `/usage/limits/policy/{meter}` | Set what happens at the limit for one allowance: stop, carry on and bill the overage, or ask a person; the warning levels; a ceiling on overage; a limit for this project alone. | admin | `rivier usage limit set` |

## limit approval

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/limits/approvals` | Requests waiting for a person to approve going past an allowance, and past decisions. | read | `rivier usage limit approval list` |
| POST | `/usage/limits/approvals/{id}/decide` | Approve or deny a request to go past an allowance. Approving lets that many more units through this period. | admin | `rivier usage limit approval decide` |

## limit draw

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/limits/draws` | Units that went through beyond the plan this period: drawn from the organisation pool, billed as overage, or approved by a person. | read | `rivier usage limit draw list` |

## limit organization

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/usage/limits/organization` | How each project of the organisation uses the allowances that can be pooled, and which are pooled. | read | `rivier usage limit organization get` |
| PUT | `/usage/limits/organization/pool` | Pool one allowance across all projects of the organisation, or stop pooling it. | admin | `rivier usage limit organization set pool` |