Organizations and Projects

Get usage timeseries

Changed on

Buckets model usage over time for one metric, optionally broken down by configured model or agent profile. Covers every project the caller can read in the organization; project_ids and agent_profile_ids narrow that scope. Buckets are calendar days, weeks (starting Monday), or months in timezone.

get/orgs/{orgID}/usage/timeseries

Request

  • Base URL: https://api.omnara.com/v1
  • URL: https://api.omnara.com/v1/orgs/{orgID}/usage/timeseries
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Host-omnara_session

Query parameters

sincestring date-time

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

untilstring 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.

timezonestring

IANA time zone that decides where each bucket starts.

interval'hour' | 'day' | 'week' | 'month'

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.

metric'sum_tokens' | 'sum_input_tokens' | 'sum_output_tokens' | 'sum_cost' | 'count_model_calls'

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

Value plotted in each bucket. Defaults to sum_tokens.

group_by'model' | 'profile'

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

group_limitinteger

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

project_idsProjectID[]

Only count usage from these projects.

agent_profile_idsAgentProfileID[]

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

include_subagentsboolean

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

Response

Usage timeseries.

metric'sum_tokens' | 'sum_input_tokens' | 'sum_output_tokens' | 'sum_cost' | 'count_model_calls' 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.

interval'hour' | 'day' | 'week' | 'month' required
group_by'model' | 'profile'
timezonestring required

IANA time zone the buckets follow.

bucket_startsTimestamp[] 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.

untilstring date-time required
active_agentsinteger required

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

Changes