# Get Usage CSV

- **Method:** `GET`
- **Path:** `/api/v1/usage.csv`
- **Operation ID:** `get_usage_csv`
- **Tags:** usage

The same month as a CSV: each run oldest first with a row per session under it - its Usage, whose
failure ended it and what was charged and refunded for it - then a `TOTAL` row, and below it the month's
grants, top-ups, expiries and adjustments. What an invoice is written from by hand - the per-role split is
in the JSON above.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Query parameters

- **`period`**: `string | null`

  The calendar month to report, YYYY-MM, in UTC. Omitted, it is the month it is now. A month you ran nothing in answers with zero totals, not a 404.

## Responses

### 200 One header row; each run oldest first, followed by one row per session of that run; then a TOTAL row. Columns: period, tenant, run\_id, session\_id, persona\_id, persona\_label, caller, occurred\_at, then the run's meters - steps, sessions, browser\_seconds, model\_usd\_hosted, model\_usd\_byo - then the session's persona\_steps, persona\_seconds (the time its steps took, without setup and teardown), usage, fault (none, saram, provider or target), usage\_usd (net) and refunded\_usd, then billable\_usd. A run's row leaves the session columns empty and a session's row leaves the run's empty, so every column sums to its TOTAL. A session that failed on Saram's side (fault saram) reads usage\_usd 0.0000 with its whole debit in refunded\_usd; usage\_usd and refunded\_usd are empty where the prepaid ledger moved no money for the session. Then one empty line and a second table, always with its header: period, tenant, kind (grant, top\_up, expiry or adjustment), bucket (included or purchased), amount\_usd (signed, to four places), created\_at and stripe\_ref (the Stripe invoice behind a top-up or a Pro grant) - each credit that came into or lapsed from the balance that month, oldest first. An expiry is in the month whose credit lapsed.

**Content type:** `application/json`

`any`

**Example:**

```json
null
```

**Content type:** `text/csv`

`string`

**Example:**

```json
""
```

### 403 the API key lacks the required scope

### 422 period is not a calendar month (YYYY-MM)