DocsObservability
Usage analytics
Query estimated provider cost, requests, errors and latency with GET /v1/usage, grouped by model, provider, route, project, key, feature, workflow or end user.
INFRO is in private early access. Running these examples requires an early-access account, an active trial or subscription entitlement, and your own provider connection. Self-serve purchasing is not generally open. See Early access.
Usage analytics summarize traffic through your own provider connections. Cost values estimate provider spend; INFRO software subscriptions are billed separately. Unpriced requests are counted explicitly so an incomplete estimate is not mistaken for a complete bill.
Totals cover only what the calling key may read: its project or its own requests by default, or the whole organization when an owner or admin granted it. See Request traces for how history access works.
Query usage
curl "https://api.infro.io/v1/usage?granularity=day&group_by=provider" \
-H "Authorization: Bearer $INFRO_API_KEY"| Parameter | Supported values |
|---|---|
granularity | hour, day (default), or month. |
group_by | model, modality, project, key, endpoint, provider, connection, route, environment, surface, workflow, step, feature, user, or tag:<key> for a promoted tag; omit for ungrouped totals. surface=gateway|playground|studio narrows any grouping to requests from gateway keys, the console Playground or INFRO Studio. workflow, step, feature, user and tag:<key> return the hundred largest groups plus one __other__ row. |
from, to | ISO timestamps. Default is the last 7 days; a single requested range may not exceed 400 days and remains subject to plan history limits. |
format | json (default) or csv. |
Response fields
Each bucket contains bucket, group, requests, units, cost, unpriced_requests, error_rate, p50_ms, p95_ms and p99_ms. Cost is USD; latency is milliseconds, measured on calls that reached your provider and answered inside the request (a refused request has no latency and is left out, and so is an async render: an image or video job's wall time from submission to result is not a request latency, and its row counts in requests and cost only). Each percentile is exact for its bucket; percentiles do not average, so a week's p95 is not the mean of seven daily ones — ask for one bucket over the window (granularity=month on a window inside one month) when you need the period's own figure. The response reports from, to, requested_from and retention_days so you can see whether the requested window was narrowed.
A query returns its buckets together: has_more is false and next_cursor is null. Split large analyses into time windows with from and to; there is no cursor pagination for usage buckets.
Response cache fields
Each bucket also carries cache_hits, cache_lookups (hits plus misses, the denominator of a hit rate), estimated_provider_cost_avoided (USD, the sum of each hit's source estimate), cache_hits_unpriced (hits whose source had no price, left out of that sum), and cache_hit_p50_ms, cache_hit_p95_ms and cache_hit_p99_ms. requests includes hits; p50_ms, p95_ms and p99_ms cover provider calls only, so a cache never makes provider latency look faster than it is. See Response cache.
Download a series as CSV
format=csv returns the data array as a file, one row per bucket and group, with the columns bucket, group, requests, units, estimated_provider_cost_usd, unpriced_requests, error_rate, p50_ms, p95_ms, with p99_ms as the last column. Columns are only ever added at the end, so a reader that takes them by position keeps working. The cost column is the same estimated provider cost as cost in JSON and excludes unpriced requests, which is why unpriced_requests sits beside it. group is empty on an ungrouped query and on requests that carried no value for the dimension; on a truncated grouping, __other__ is the remainder of every group outside the hundred largest.
The envelope's facts are response headers rather than lines in the file: X-INFRO-Granularity, X-INFRO-Group-By, X-INFRO-From, X-INFRO-To, X-INFRO-Requested-From, X-INFRO-Groups-Truncated and X-INFRO-Retention-Days. The console offers this as Chart data (CSV) beside each Analytics chart. It is a different dataset from the FOCUS cost dataset, which is charge-grain and built for FinOps tools.
The CSV gains two columns, after p95_ms and before p99_ms: cache_hits and estimated_provider_cost_avoided_usd.
Attribution and history
Developer includes 7 days of queryable history, Startup 14, Team 30, Business 90 and Enterprise 365. The API reports the applied window. Optional payload logging is a separate opt-in with plan limits; see Privacy.
group_by=user groups by the user_id you attach in request metadata, and group_by=feature by metadata.feature or X-INFRO-Feature. A tag groups only once it is promoted (up to five keys, under Cost centers → Attribution settings); an unpromoted tag:<key> is a 400 tag_not_promoted. Session ids and unpromoted tags are filters on request history. In the console, Analytics → Where the spend went offers the same groupings, shows what share of estimated spend carries the chosen field, and opens a row's requests. For custom provider rates and cost reconciliation, see Billing.