Projects

List project usage events

The rows a rollup summed — one per metered occurrence, most recent first. Takes the same narrowings the meter does, so a query that produced a bucket answers here unchanged and reads back what went into it. This is the audit and reconciliation view: what was measured, when, against which agent, session, actor and provider, and what each component was priced at.

An id naming nothing in this project yields an empty page rather than dropping the filter, so a mistyped narrowing can never widen the list past what was asked for.

get/v1/projects/{project_id}/usage/events

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/usage/events
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Query parameters

meter_typestring
Example:llm_tokens

Narrow the rollup to one meter type (llm_tokens, compute_execution, api_request, storage, tool_execution). Omit to include every meter. Useful with group_by=model, whose dimension otherwise mixes model ids with platform SKUs. An unrecognized value yields an empty rollup, not an error.

session_idstring
Example:sess_V1StGXR8Z5jdHi6B

Narrow the whole rollup — every bucket and the top-level totals alike — to one session's traffic. Combines with group_by: group_by=day&session_id=... is one conversation's spend per day, group_by=model the same spend split by model. This is the figure behind the usage roll-up a single session read carries, broken down. An id naming no session in this project yields an empty rollup, never the project total.

actor_idstring
Example:actor_V1StGXR8Z5jdHi6B

The same narrowing, for one end user across every session they appear in — what a customer re-billing their own users charges each of them for. An id naming no actor in this project yields an empty rollup, never the project total.

agent_idstring
Example:agent_V1StGXR8Z5jdHi6B

Narrow to one agent's traffic, across every session, run and trigger that dispatched it.

ai_provider_idstring
Example:aip_V1StGXR8Z5jdHi6B

Narrow to the spend billed against one provider record — a routed generation's serving target, or the agent's pinned provider.

orchestration_run_idstring
Example:orun_V1StGXR8Z5jdHi6B

Narrow to the events one orchestration run metered.

orchestration_idstring
Example:orch_V1StGXR8Z5jdHi6B

Narrow to the runs of one orchestration — the ones it started itself, never the subtree a loop or sub-orchestration node started under it, which is metered against the child orchestration where it was incurred. Additive: summed across a project's orchestrations the figures reach the project total exactly once.

generation_idstring
Example:gen_V1StGXR8Z5jdHi6B

Narrow to one generation's events. A generation writes more than one when it meters several dimensions, such as tokens and compute.

trace_idstring
Example:trace_V1StGXR8Z5jdHi6B

Narrow to the events recorded under one trace.

sourcestring
Example:eval

Narrow by what the spend was incurred for — eval and eval_judge are verification spend. Ordinary traffic carries no source, so it cannot be selected by this filter; omit the filter for everything.

trigger_idstring
Example:trig_V1StGXR8Z5jdHi6B

Narrow to the spend one trigger initiated. Matched as recorded rather than resolved, so it still selects the spend of a trigger that has since been deleted.

action_idstring

Narrow to one caller-supplied action label, for per-action spend. Matched as recorded, like trigger_id.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

offsetinteger

Results to skip. Negative or not an integer it is 400.

Response

One page of usage events.

totalinteger required
limitinteger required
offsetinteger required

Example response

{
  "data": [
    {
      "id": "ue_V1StGXR8Z5jdHi6B",
      "meter_type": "llm_tokens",
      "provider": "bedrock",
      "model": "nova-lite-v1",
      "components": [
        {
          "component": "input_tokens",
          "quantity": 1200,
          "unit": "token"
        }
      ]
    }
  ],
  "total": 1280,
  "limit": 50
}

Changes

No recorded changes to this operation across all 1 revision of this API.