> Source: https://vitna.ai/docs/api/v1/engine/usage
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/usage.md
> Corpus index: https://vitna.ai/llms.txt
# Pushing usage
The one write route this API mounts, and the only route a machine
authenticates to. A runtime pushes what its own ledger says served each lane
on a day that has ended, and each batch lands as readings on `/console`.
```
POST /api/v1/usage
```
```
Authorization: Bearer vitna_push_...
```
The key is org-scoped, minted by an operator with
[`org:key:create`](../../../cli/keys.md), shown once, and held as a hash: a
push may only name workloads of the org the key belongs to.
## The body
One payload is one closed UTC day:
```json
{
"window": "2026-08-24",
"source": "policy ecb93b2a5c50...",
"rows": [
{ "workload": "convexity/deep-research", "sku": "anthropic/claude-opus-4-8", "units": 3, "windowUnits": 4 },
{ "workload": "convexity/deep-research", "sku": "openai/gpt-5.6-luna", "units": 1, "windowUnits": 4 }
]
}
```
`source` is where the readings trace to, normally the policy digest that was
routing when the requests ran; it is carried onto every reading's
`source_ref` beside the key's id. `windowUnits` is the workload's own total
for the day, stored on every row so a share stays a share.
## What a push is, and is not
A push is a reading, `origin: runtime`, append-only. It never adopts:
`confirms_decision_id` stays null and no workload's incumbent moves, because
a machine that pushed enough traffic being able to move what the register
says a lane runs would be the register taking dictation. Adoption stays an
operator act through [`aperture:usage:import`](../../../routing/usage-import.md).
A batch is atomic. Any refused row refuses the whole batch and nothing lands,
for the reason a partial config is refused.
A replay is one fact. The record keeps one reading per workload per window
per sku, so re-pushing a day it already holds answers with `alreadyStood`
rather than landing twice. That is also why only closed days are accepted: a
reading of today would be a total that is wrong by midnight, standing
permanently.
## The answer
```json
{ "landed": 2, "alreadyStood": 0, "refusals": [] }
```
`201` when anything landed, `200` when everything already stood, and on any
refusal a `4xx` whose `refusals` array names every fault at once rather than
one per round trip.
| Refusal | Status |
|---|---|
| No ingest database on this instance | 503 |
| No key, an unknown key, or a revoked one (named, with "mint another") | 401 |
| A body over 1 MiB (1048576 bytes), counted as it arrives | 413 |
| A malformed window, source or row, each fault listed | 400 |
| A day that has not ended | 400 |
| A workload of another org, or one the record does not hold | 403 |
## Who can read what lands
Not this route, and not the role behind it: `vitna_ingest` may insert a
reading and may never select one back, which
`deploy/provision-usage-ingest.sh` proves against the live role. Readings
reach people on [`/console`](../../../quickstart.md), scoped by org
membership, on the volume line and the confirmation under each value.