Reporting API

The Usage API answers fixed questions: what did this agent do, what did it cost. The Reporting API is the open version of the same data. You choose the dimensions, the measures, the grain, and the window, and you get rows back.

Ask what is available

GET /reporting/metric-catalog returns the fields you can bind, each with a field, a kind, a description, and whether it is derived. It also returns default_constants, which matter more than they look, and are explained below. Required scope: reports:read.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/reporting/metric-catalog"

kind has three values, and the middle one is easy to miss.

A field picker that filters to dimensions and measures finds none of the counts, because the counts are all base. Bind them from base, as the example below does.

Read the catalog rather than hardcoding a field list. It is a curated starter set rather than a projection of the fact tables, so a new fact column appears here when someone adds it, not automatically; reading it still beats a list frozen into your client.

Run a query

POST /reporting/query aggregates the daily facts server-side for one query binding. Required scope: reports:read.

curl -X POST "https://api.hyperstruck.com/reporting/query" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "<SPACE_ID>",
    "window": "last_30_days",
    "binding": {
      "dimensions": ["day", "host"],
      "measures": ["learnings_applied", "learnings_retrieved"],
      "grain": "day",
      "limit": 500
    }
  }'

The response carries rows, row_count, truncated, period_start and period_end_exclusive, the window and query_binding it actually ran, plus constants and is_illustrative.

The dollar measures are derived, and you own the assumptions

Money is not measured, it is calculated. A dollar measure comes from a count of things that happened multiplied by assumptions about what each one is worth: minutes saved per retrieval, minutes of rework per mislead, minutes to relearn something forgotten, an hourly rate. Those live per space.

GET /reporting/defaults/{space_id} returns them, and PUT replaces them. Reading takes reports:read; writing takes reports:write, so it is a portal action rather than an API-key one.

curl -H "Authorization: Bearer <API_KEY>" \
  "https://api.hyperstruck.com/reporting/defaults/<SPACE_ID>"

On top of the scope, reading requires space viewer and writing requires space steward, which organization admins also qualify as. A space with no row of its own falls back to product defaults.

The base counts are not affected by any of this. Runs, retrievals, applications, misleads, and spend are observed. Every derived measure is not, and that includes the ones denominated in minutes and rates rather than dollars, so read the derived flag rather than assuming money is the only calculated thing.

Save a view

Charts pin a query_binding and a viz_spec together so a question can be re-asked without rebuilding it.

Reading takes reports:read. Creating, updating, or deleting takes reports:write plus can_publish on the space, and reports:write is portal-session only.

Assemble a dashboard

Everything in this table needs reports:write except the two reads, which need reports:read. A placement carries chart_id, row_index, col_index, and optionally col_span and sort_key. col_index + col_span must not exceed the dashboard's columns, and a request that breaks that is refused rather than silently clipped. Because PUT replaces the whole set, send the placements you want to keep along with the ones you are adding.

Related pages

• Usage API for the fixed reports and the billing view
• Access control (FGA and RBAC) for spaces, viewers, stewards, and can_publish
• Grounded success for what an assisted run actually means before you chart it