Skip to main content
GET
Get usage timeseries

Authorizations

Authorization
string
header
required

An opaque Omnara personal or organization bearer token.

Path Parameters

orgID
string
required
Pattern: ^org_[a-z2-7]{26}$

Query Parameters

since
string<date-time>

Only tally model calls started at or after this instant. Omit to start from the earliest recorded call.

until
string<date-time>

Only tally model calls started before this instant. Must be later than since when both are given. Omit to include calls up to now.

timezone
string
default:UTC

IANA time zone that decides where each bucket starts.

Maximum string length: 64
interval
enum<string>

Bucket width. Omit to pick one from the window length: days up to 92 days, weeks up to 730 days, months beyond. Hourly buckets are used only when requested. The window may span at most 400 buckets.

Available options:
hour,
day,
week,
month
metric
enum<string>

Value plotted in each bucket. Defaults to sum_tokens. sum_tokens is input plus output tokens. sum_cost is provider-reported cost in USD. count_model_calls counts model calls that recorded usage.

Available options:
sum_tokens,
sum_input_tokens,
sum_output_tokens,
sum_cost,
count_model_calls
group_by
enum<string>

Break the metric down into one series per group. Omit for a single series.

Available options:
model,
profile
group_limit
integer
default:8

With group_by, how many groups get their own series, ranked by the metric. The rest are folded into one other series.

Required range: 1 <= x <= 20
project_ids
string[]

Only count usage from these projects.

Required array length: 1 - 100 elements
Pattern: ^proj_[a-z2-7]{26}$
agent_profile_ids
string[]

Only count usage from top-level agents launched from these agent profiles.

Required array length: 1 - 100 elements
Pattern: ^aprf_[a-z2-7]{26}$
include_subagents
boolean
default:false

With agent_profile_ids, also count usage from subagents spawned by those agents.

Response

Usage timeseries.

metric
enum<string>
required

sum_tokens is input plus output tokens. sum_cost is provider-reported cost in USD. count_model_calls counts model calls that recorded usage.

Available options:
sum_tokens,
sum_input_tokens,
sum_output_tokens,
sum_cost,
count_model_calls
interval
enum<string>
required
Available options:
hour,
day,
week,
month
timezone
string
required

IANA time zone the buckets follow.

bucket_starts
string<date-time>[]
required

Start of each bucket in timezone, oldest first, including buckets without usage. The first bucket starts at the beginning of the interval containing since, but only usage at or after since counts.

until
string<date-time>
required

End of the window; usage at or after this instant is excluded.

totals
object
required

All usage in the window, regardless of metric and group_by.

active_agents
integer<int64>
required

Agents, not counting subagents, that made at least one model call in the window.

Required range: x >= 0
series
object[]
required

Without group_by, a single all series. With it, one series per ranked group, most first, then an other series when usage remains.

group_by
enum<string>
Available options:
model,
profile