Usage API

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

Own-tenant endpoints

GET /usage/summary

No query params are required.

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

Required scope: usage:read

The summary response includes:

GET /usage/runs

No query params are required.

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

Required scope: usage:read

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"

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

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.

Related pages

• 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