GET /v1/usage

Call	GET /v1/usage
Price	free
Scope	account:read
Operation id	getUsage

What it does

Calls, billed calls and charges between two UTC days, grouped by day, project, key or decision. Totals equal the ledger. Free. Scope: account:read.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

Request

curl -X GET 'https://api.askverdict.io/v1/usage?from=2026-11-01&to=2026-11-01' \
  -H "Authorization: Bearer $VERDICT_API_KEY"

Example response

200: Usage over the window.

200 response

{
  "from": "2026-11-01",
  "to": "2026-11-07",
  "group_by": "decision",
  "rows": [
    {
      "group": "qualify_firm",
      "calls": 1200,
      "billed_calls": 1180,
      "decision_usd": 5.9,
      "vendor_usd": 0,
      "total_usd": 5.9
    },
    {
      "group": "triage_reply",
      "calls": 310,
      "billed_calls": 310,
      "decision_usd": 0.93,
      "vendor_usd": 0,
      "total_usd": 0.93
    }
  ],
  "totals": {
    "calls": 1510,
    "billed_calls": 1490,
    "decision_usd": 6.83,
    "vendor_usd": 0,
    "total_usd": 6.83
  }
}

Parameters

Name	In	Type	Required	Description
from	query	string (date)	yes	First UTC day included.
to	query	string (date)	yes	Last UTC day included.
group_by	query	enum: “day”, “project”, “key”, “decision”	no	Grouping; default day.
x-verdict-version	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is 2026-11-01.

Response fields (200)

Schema UsageResponse.

Field	Type	Required	Description
from	string (date)	yes	First day included.
to	string (date)	yes	Last day included.
group_by	enum: “day”, “project”, “key”, “decision”	yes	Grouping used.
rows	array of object	yes	One row per group.
rows[].calls	integer	yes	Calls made.
rows[].billed_calls	integer	yes	Calls billed (misses and errors are free).
rows[].decision_usd	number	yes	Decision charges. US dollars, up to 6 decimals.
rows[].vendor_usd	number	yes	Vendor pass-through charges. US dollars, up to 6 decimals.
rows[].total_usd	number	yes	Total charges. US dollars, up to 6 decimals.
rows[].group	string	yes	Group key: a date, project id, key id or decision name.
totals	object	yes	Totals over the window; equal to the ledger sums.
totals.calls	integer	yes	Calls made.
totals.billed_calls	integer	yes	Calls billed (misses and errors are free).
totals.decision_usd	number	yes	Decision charges. US dollars, up to 6 decimals.
totals.vendor_usd	number	yes	Vendor pass-through charges. US dollars, up to 6 decimals.
totals.total_usd	number	yes	Total charges. US dollars, up to 6 decimals.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
400	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request).
401	Missing, malformed, revoked or expired API key, or a bad webhook signature (unauthorized).
403	The key lacks the scope this operation needs (forbidden_scope).
429	Rate limited (rate_limited). Wait Retry-After seconds.
500	Unexpected server error (internal). Not billed; retry with the same Idempotency-Key.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.