---
title: "Usage for this workspace"
method: GET
path: "/v1/usage"
tags: ["usage"]
---

# Usage for this workspace

`GET /v1/usage`

## Request

- Base URL: `https://api.hyperresearch.ai`
- URL: `https://api.hyperresearch.ai/v1/usage`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `hr_session`

Runs by tier and metered usage by kind for the period, plus the account plan, spend cap and month-to-date spend. Reads D1 only — never Stripe. `charged` is the runs that were billed, tier by tier, and `totals.charged_cents` is exactly their sum; `included` lists the trial-covered runs apart, at $0, each flagged `included_in_trial`. Each `metered` kind separates its `charges` from its `refunds`, so a net quantity is never shown beside a gross event count.

## Query parameters

- `from` string
- `to` string

## Response `200`

Usage

- UsageSummary
  - `period` object, required
    - `from` string, required
    - `to` string, required
  - `workspace_id` string, required
  - `runs` object[], required
    - `tier` string, required
    - `runs` integer, required: Runs of this tier created in the period.
    - `price_cents` integer, required: Reserved list price on the control rows. 0 for a run an included (trial) allowance covered — this is NOT what was charged.
    - `amount_cents` integer, required: What the billing ledger metered for these runs, refunds included. Sums to `totals.run_amount_cents`.
    - `metered_runs` integer, required: How many of these runs have a ledger row yet. `runs - metered_runs` is the number still in flight.
    - `included_runs` integer, required: How many of these runs an included (trial) allowance covered, metered at $0.
    - `charged_runs` integer, required: `runs - included_runs`: the runs no allowance covered.
    - `charged_cents` integer, required: What the ledger metered for the charged runs alone.
    - `included_cents` integer, required: What the ledger metered for the included runs. $0 by definition.
    - `complimentary_runs` integer: How many of these runs an operator grant comped (0041). Taken OUT of `charged_runs`, never netted into it.
    - `complimentary_cents` integer: What the comped runs would have cost — the real price, which their ledger rows carry. Not part of `charged_cents`.
  - `charged` object[], required: Runs that were billed this period, by tier, with what they cost. `totals.charged_cents` is exactly the sum of these amounts — no other number has to be subtracted to arrive at it (E2E2-07).
    - `tier` string, required
    - `runs` integer, required
    - `amount_cents` integer, required
    - `metered_runs` integer, required
    - `included_in_trial` false, required
  - `included` object[], required: Trial-covered runs, listed apart from the charged ones so "$0.00" reads as "included" rather than as "free by accident".
    - `tier` string, required
    - `runs` integer, required
    - `amount_cents` integer, required: Always 0: an included run is not charged.
    - `included_in_trial` true, required
  - `complimentary` object[]: Runs an operator grant comped (0041), listed apart from the charged ones and NOT included in `totals.charged_cents`. Absent when this account has none.
    - `tier` string, required
    - `runs` integer, required
    - `amount_cents` integer, required: The real price of these runs, which is what their ledger rows carry — a comped run is not a $0 run.
    - `complimentary` true, required
  - `metered` object[], required
    - `kind` string, required
    - `quantity` integer, required: Net of refunds, like `amount_cents` beside it. To show a quantity next to `events`, use `charges.quantity`: it counts the same population (E2E2-07).
    - `amount_cents` integer, required: Net of refunds.
    - `events` integer, required: The metered events of this kind in the period — charged and included together, refunds excluded. ALWAYS equal to `charges.quantity` for a one-unit-per-event meter such as runs, because they are the same rows counted twice; a row that read `Research runs — 7 — $0.00 — 8 events` was counting a refund as an eighth run (E2E4A-10). Show `charges.amount_cents` beside it for what those events were charged.
    - `gross_events` integer, required: Every ledger row of this kind, refunds included. `events + refunds.events`.
    - `charges` UsageTotals, required: The non-negative rows only — the metered events themselves, charged and included alike. `charges.quantity === events` for a per-run meter.
      - `quantity` integer, required
      - `amount_cents` integer, required
      - `events` integer, required
    - `refunds` object, required: The negative rows only; `quantity` and `amount_cents` stay negative. A refund reverses an event, it is not an event, so it is never counted in `events`.
      - `quantity` integer, required
      - `amount_cents` integer, required
      - `events` integer, required
  - `totals` object, required
    - `amount_cents` integer, required: Every metered kind in this workspace for the period.
    - `events` integer, required
    - `runs` integer, required: Runs created in the period, all tiers.
    - `metered_runs` integer, required
    - `included_runs` integer, required
    - `charged_runs` integer, required: Runs created in the period that no allowance covered.
    - `charged_cents` integer, required: What the charged runs cost, and exactly the sum of `charged[].amount_cents`. This is the period total a customer is asked to believe.
    - `run_amount_cents` integer, required: The run-kind slice of `amount_cents`; equals the sum of `runs[].amount_cents`.
    - `complimentary_runs` integer: Runs created in the period that an operator grant comped (0041).
    - `complimentary_cents` integer: What those runs would have cost, and exactly the sum of `complimentary[].amount_cents`. Deliberately NOT part of `charged_cents`: the account was not asked to pay it.
  - `licensed_articles` object, required: Licensed-article spend (rung `LT`), at cost, from the fetch lane's own source ledger — NOT from `usage_events` and NOT part of `totals`. The two ledgers are separate on purpose: one is what this workspace was charged, the other is what a vendor charged us for a page, and summing them would double-count. All zeros when nothing was licensed, which is the shipping state.
    - `month` string, required: `YYYY-MM`, the month the source ledger books against.
    - `articles` integer, required: Licensed article purchases attributed to this workspace this month, settled or in flight.
    - `settled_micros` integer, required: What the vendor confirmed charging, in micro-USD (1000000 = $1.00). Micro-USD and not cents because a licensed page costs $0.001 to $1.00, and most purchases would round to free.
    - `reserved_micros` integer, required: Booked and not yet settled: a purchase in flight, held at its worst case.
    - `unresolved_micros` integer, required: Of `reserved_micros`, the part whose outcome is unknown and awaiting reconciliation against the vendor's own record. Reported apart because an unknown outcome is neither confirmed spend nor available headroom.
  - `account` object, required
    - `plan` string, required
    - `spend_cap_cents_month` integer, required
    - `month_to_date_cents` integer, required: Account-wide charge for the current month, across EVERY workspace of the account — not just this one. Compare with `totals.amount_cents`, which is this workspace only.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: Insufficient scope or plan
- `404`: Not found
- `429`: Rate limited or over quota
- `500`: Internal error

---

[API](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api.md) · [All operations](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/revisions/726ef831ebf4?raw)