Usage events
The Usage events screen lets you browse the raw usage events of your tenant, one per gateway call, with the
units consumed and the estimated, measured and billed cost. Portal path: /finops/usage (menu FinOps >
Usage events). FinOps analysts and auditors use it to explain a cost line down to the call that produced it.
What the screen shows
| Area | Content |
|---|---|
| Filters | Provider, Model id, Agent id, Run id (free text), Usage type (llm, embedding, image, audio, video, tool, gpu_local, rag), Status (estimated, measured, billed), From and To (ISO 8601 timestamp, for example 2026-01-01T00:00:00Z). |
| Usage events table | Columns: Time, Usage type, Provider, Model, Agent id, Input tokens, Output tokens, Estimated, Measured, Billed (each amount in its own currency), Status. Newest first, 50 rows per page. |
| Detail panel | A click on a row opens the full event (units, cost, identifiers) as JSON. The panel shows the row already loaded: there is no extra call. |
| Empty state | No usage event: events are produced by every gateway call. |
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Filter | Applies the filters filled in (empty filters are ignored). | GET /v1/finops/usage (provider, model_id, agent_id, run_id, usage_type, status, from, to, limit, cursor) | Readers of the FinOps section |
| Refresh (round arrow icon) | Reloads the list. | GET /v1/finops/usage | Readers of the FinOps section |
| Load more | Loads the next page with the cursor returned by the server. | GET /v1/finops/usage (cursor) | Readers of the FinOps section |
| Click on a row | Opens the detail panel of the event. | None | Readers of the FinOps section |
| Retry (error panel) | Sends the list request again. | GET /v1/finops/usage | Readers of the FinOps section |
The screen has no create button: the events are written by the gateways and the SDK (POST /v1/finops/usage,
roles finops, tenant_admin, agent, developer).
Roles
| Role | Access |
|---|---|
finops, tenant_admin, auditor | Open the screen and read the events (READ_ROLES of services/control-plane/src/eai/domains/finops/__init__.py). |
platform_admin | Opens the screen; the route needs a tenant context (tenant_required otherwise). |
developer, viewer, security_officer | Allowed by the API, but the FinOps section of the portal menu does not open for them. |
Typical tasks
Explain the cost of one run
- Copy the run id. The run id ties every call of an agent run together. Copy it from Runs.
Expected result: you have an id such as
<run-id>. If it fails: open the run in Agents > Runs and copy the id from its detail. - Filter on the run. Paste the id in Run id and click Filter. Expected result: the table lists only the calls of that run. If it fails: if No usage event appears, check that the id has no space and that the run called a model.
- Open an event. Click a row to read the units and the cost details.
Expected result: the panel shows the JSON of the event, with
cost.estimated,cost.measuredandcost.billed. If it fails: close and reopen the panel, or click Refresh.
List the calls of one model that are not reconciled yet
- Filter on the model and the status. Fill Model id and choose
measuredin Status, then click Filter. Themeasuredevents have a measured cost but no billed cost yet. Expected result: the table lists the calls of that model waiting for reconciliation. If it fails: an errorvalidation_erroron From or To means the timestamp is not ISO 8601. - Reconcile them. Import the provider export of the period in Reconciliation.
Expected result: after the run, the same filter with
billedlists the events. If it fails: see the troubleshooting of the Reconciliation page.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Error validation_error (HTTP 422): "The request failed validation." | From or To is not an ISO 8601 timestamp. | Write the date as 2026-01-01T00:00:00Z. |
Error forbidden (HTTP 403) | No role of READ_ROLES. | Ask for the finops role. |
Error tenant_required (HTTP 403) | Platform administrator without a tenant. | Sign in to a tenant. |
| No usage event | No call matches the filters, or the gateway did not report usage. | Remove filters; check the gateway in Gateway playground. |
| Billed column empty | The event has not been reconciled with a provider export. | Run the reconciliation in Reconciliation. |