> 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.
