Usage API

Inspect your tenant's usage summary, cost rollups, and recent runs, with per-agent reporting for individual agents.

Use the Usage API to see aggregate run usage, estimated cost rollups, learning operation counts, and recent run history for your own tenant.

Access control

Usage endpoints require the usage:read scope. Data is tenant-scoped through row-level security. See Access control (FGA and RBAC).

Lead with the default tenant view

Start with the no-query-params version first. Add filters only when you need them.

Run list responses include tenant_id, window, period_start, period_end_exclusive, items, and next_cursor. Each item is a billing-safe projection with IDs, status, worker profile, timestamps, compute seconds, and estimated cost fields. Items intentionally omit goal, metadata, and error.

Per-agent usage

`GET /agents/{agent_id}/usage/summary`

Returns usage aggregates for one agent.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/agents/<AGENT_ID>/usage/summary"

Prop

Type

The response includes agent_id, window, period_start, period_end_exclusive, and agent_runs aggregates with run counts by status, session count, compute totals, and estimated cost rollups.

Required scope: usage:read

Spend limits

`GET /billing/summary`

Your tenant's spend limit and how much of it is left.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/billing/summary"

Required scope: usage:read

All amounts are USD. The response carries plan_code, window_kind, period_start, period_end_exclusive, hard_limit_usd, soft_limit_usd, current_spend_usd, active_reservations_usd, committed_usd, available_usd, percent_used, and status.

Reserved matters: work already dispatched but not yet billed is held against your limit, so available_usd reflects what you can actually still spend rather than what has settled.

There are two caps and they behave differently

hard_limit_usd is enforced: work that would exceed it is refused with a 403 rather than run and billed. soft_limit_usd is not enforced. Crossing it logs a warning and nothing else, so treat it as an early signal to act on, never as a control that will stop spend.

Null does not mean zero

On an unlimited tenant, status is unlimited and hard_limit_usd, soft_limit_usd, available_usd and percent_used are all null. Branch on status before doing arithmetic on those fields.

Call it before dispatching optional work when your integration needs to show budget status.

Claim activity

`GET /usage/claim-assists`

How often the claims shelf actually helped, over a recent window. It answers "assisted N of M runs", and it is about realized value rather than cost: these events never bill.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/usage/claim-assists"

Prop

Type

Required scope: usage:read

The response carries tenant_id, window_hours, applied (bound claims proven correct at execution), misled (bound claims proven wrong), assisted_runs, and total_runs. The last two are the N and M of assisted N of M runs. Watch misled as well as applied: a rising misled means the corpus is confidently wrong about something and is worth curating.

A claim is billed once, when it can first help you

Claim writes are metered on whether the claim could actually reach an agent's planning at the moment it was written. A claim that entered unable to be used, such as a correctly held injection attempt, bills only if it later earns its place, so poisoned observations cannot inflate your bill. The assist counts above are separate and never bill.

Common next knobs

Use window to switch from the default last_7_days view. Valid values are last_7_days, last_30_days, calendar_quarter, and calendar_year.
Use limit and cursor when paging through run history.
Use as_of when you want a report anchored to a specific point in time.
Use include_summary=true on GET /agents when you want per-agent usage summaries in the agent inventory.

Reporting API for open queries over the same daily rows, and saved charts and dashboards
Access control (FGA and RBAC) for scope requirements
Quickstart for the first agent flow
Agents API for the endpoints that create runs
Plans API for directly inspecting prior workflow matches
Learnings API for manual learning operations that may appear in usage reporting
Claims API for the curation surface behind claim activity

Own-tenant endpoints

`GET /usage/summary`

`GET /usage/runs`

Per-agent usage

`GET /agents/{agent_id}/usage/summary`

Spend limits

`GET /billing/summary`

Claim activity

`GET /usage/claim-assists`

Common next knobs

On this page