Usage and allowances

GET/v1/usage

What this key's holder has spent over a window, and the state of each capped allowance this month.

What this key's holder has spent over a window (their own requests within the organisation), and the state of every capped allowance this calendar month. Rungs with no allowance are not listed; active: false means nothing is capped. The figures behind each rung (the cap, what was spent, what is left, who set it) are included only when the key's holder may read the organisation's costs.

Example

Against https://platform.memtro.com, with your key in MEMTRO_API_KEY.

curl "https://platform.memtro.com/v1/usage?days=7" \
  -H "Authorization: Bearer $MEMTRO_API_KEY"

import os, requests

r = requests.get(
    "https://platform.memtro.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['MEMTRO_API_KEY']}"},
    params={"days": 7},
)
r.raise_for_status()
print(r.json())

const res = await fetch("https://platform.memtro.com/v1/usage?days=7", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.MEMTRO_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log(await res.json());

A key without the organisation's cost figures: the rungs carry their state only.

{
  "object": "usage",
  "window": { "from": "2026-11-06", "to": "2026-11-12", "label": "the last 7 days", "requests": 412, "input_tokens": 1840211, "output_tokens": 96402, "total_tokens": 1936613, "tool_calls": 388, "errors": 3 },
  "allowances": {
    "period": "2026-11",
    "period_label": "November 2026",
    "active": true,
    "org_figures": false,
    "rungs": [
      { "kind": "general", "level": 5, "role": "primary", "state": "low" },
      { "kind": "general", "level": 3, "role": "primary", "state": "ok" }
    ]
  }
}

Authentication

An API key, as Authorization: Bearer or x-api-key.

Every reply, errors included, carries x-request-id and request-id headers with the same id, starting req-. Quote it to support.
Browsers may call it from any origin: it answers CORS preflights and allows the Authorization, x-api-key and Anthropic version headers.

Query parameters

daysintegerOptional: The last this many days, 1 to 400. Anything else reads as 30, never an error.
Default:
30
fromstringOptional: A start date, YYYY-MM-DD, with to. A valid pair wins over days; a reversed pair is swapped, and a span over 400 days is cut to the last 400.
tostringOptional: An end date, YYYY-MM-DD, with from.

Response

200application/json

The window and the allowances.

object"usage"Optional

Always usage.

windowobjectOptional

The window asked for.

3 fields of window

from, tostringOptional: Its dates, YYYY-MM-DD.
labelstringOptional: In words, such as the last 30 days.
requests, input_tokens, output_tokens, total_tokens, tool_calls, errorsintegerOptional: The totals.

allowancesobjectOptional

This month's allowances.

5 fields of allowances

periodstringOptional

The month they count in, YYYY-MM.

period_labelstringOptional

The month in words.

activebooleanOptional

Whether anything is capped.

org_figuresbooleanOptional

Whether the rungs carry the organisation's own figures.

rungsarray of objectsOptional

Each capped rung.

6 fields of rungs

kindstringOptional

Which ladder.

One of general or coding.

levelintegerOptional

The difficulty level, 1 to 5.

rolestringOptional

Which rung of the level.

One of primary, secondary or tertiary.

statestringOptional

low is 10% or less left.

One of ok, low or exhausted.

limit, used, remainingintegerOptional

Tokens, when org_figures is true.

set_byobjectOptional

When org_figures is true: who set the cap, {kind: "org" | "team", id, name}.

Errors

In the OpenAI envelope, {"error": {"message", "type", "param", "code"}}. What each code means and what to do about it is in the error catalogue.

Status	Code	When
401	`invalid_api_key`	The key is missing, malformed, revoked or expired.
402	`subscription_inactive`	The organisation has no active subscription.