> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # Get usage timeseries > 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`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /orgs/{orgID}/usage/timeseries openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara - url: /api/v1 description: Self-hosted Omnara, relative to the deployment origin security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Integrations description: >- Connect project integrations, route conversations, and manage launch settings. externalDocs: description: Guide url: https://docs.omnara.com/integrations/overview - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/usage/timeseries: parameters: - name: orgID in: path required: true schema: $ref: '#/components/schemas/OrganizationID' get: tags: - Organizations and Projects summary: Get usage timeseries description: >- 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`. operationId: getOrgUsageTimeseries parameters: - $ref: '#/components/parameters/UsageSince' - $ref: '#/components/parameters/UsageUntil' - name: timezone in: query required: false schema: type: string default: UTC maxLength: 64 description: IANA time zone that decides where each bucket starts. - name: interval in: query required: false schema: $ref: '#/components/schemas/UsageTimeseriesInterval' description: >- 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. - name: metric in: query required: false schema: $ref: '#/components/schemas/UsageTimeseriesMetric' description: Value plotted in each bucket. Defaults to `sum_tokens`. - name: group_by in: query required: false schema: $ref: '#/components/schemas/UsageTimeseriesGroupBy' description: >- Break the metric down into one series per group. Omit for a single series. - name: group_limit in: query required: false schema: type: integer minimum: 1 maximum: 20 default: 8 description: >- With `group_by`, how many groups get their own series, ranked by the metric. The rest are folded into one `other` series. - name: project_ids in: query required: false schema: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/ProjectID' description: Only count usage from these projects. - name: agent_profile_ids in: query required: false schema: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/AgentProfileID' description: >- Only count usage from top-level agents launched from these agent profiles. - name: include_subagents in: query required: false schema: type: boolean default: false description: >- With `agent_profile_ids`, also count usage from subagents spawned by those agents. responses: '200': description: Usage timeseries. content: application/json: schema: $ref: '#/components/schemas/UsageTimeseries' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '503': $ref: '#/components/responses/ServiceUnavailable' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' components: schemas: OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ UsageTimeseriesInterval: type: string enum: - hour - day - week - month x-enum-varnames: - UsageTimeseriesIntervalHour - UsageTimeseriesIntervalDay - UsageTimeseriesIntervalWeek - UsageTimeseriesIntervalMonth UsageTimeseriesMetric: type: string description: >- `sum_tokens` is input plus output tokens. `sum_cost` is provider-reported cost in USD. `count_model_calls` counts model calls that recorded usage. enum: - sum_tokens - sum_input_tokens - sum_output_tokens - sum_cost - count_model_calls x-enum-varnames: - UsageTimeseriesMetricSumTokens - UsageTimeseriesMetricSumInputTokens - UsageTimeseriesMetricSumOutputTokens - UsageTimeseriesMetricSumCost - UsageTimeseriesMetricCountModelCalls UsageTimeseriesGroupBy: type: string enum: - model - profile x-enum-varnames: - UsageTimeseriesGroupByModel - UsageTimeseriesGroupByProfile ProjectID: type: string pattern: ^proj_[a-z2-7]{26}$ AgentProfileID: type: string pattern: ^aprf_[a-z2-7]{26}$ UsageTimeseries: type: object additionalProperties: false required: - metric - interval - timezone - bucket_starts - until - totals - active_agents - series properties: metric: $ref: '#/components/schemas/UsageTimeseriesMetric' interval: $ref: '#/components/schemas/UsageTimeseriesInterval' group_by: $ref: '#/components/schemas/UsageTimeseriesGroupBy' timezone: type: string description: IANA time zone the buckets follow. bucket_starts: type: array description: >- 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. items: $ref: '#/components/schemas/Timestamp' until: $ref: '#/components/schemas/Timestamp' description: End of the window; usage at or after this instant is excluded. totals: $ref: '#/components/schemas/UsageTotals' description: All usage in the window, regardless of `metric` and `group_by`. active_agents: type: integer format: int64 minimum: 0 description: >- Agents, not counting subagents, that made at least one model call in the window. series: type: array description: >- Without `group_by`, a single `all` series. With it, one series per ranked group, most first, then an `other` series when usage remains. items: $ref: '#/components/schemas/UsageTimeseriesSeries' Timestamp: type: string format: date-time UsageTotals: type: object additionalProperties: false required: - model_calls - tokens - cost properties: model_calls: type: integer format: int64 minimum: 0 description: Model calls that recorded token usage or a provider-reported cost. tokens: $ref: '#/components/schemas/UsageTokenTotals' cost: $ref: '#/components/schemas/UsageCostTotals' UsageTimeseriesSeries: type: object additionalProperties: false required: - kind - total - values properties: kind: type: string enum: - all - model - profile - no_profile - other x-enum-varnames: - UsageTimeseriesSeriesKindAll - UsageTimeseriesSeriesKindModel - UsageTimeseriesSeriesKindProfile - UsageTimeseriesSeriesKindNoProfile - UsageTimeseriesSeriesKindOther description: >- `no_profile` groups usage from agents launched without a profile; `other` folds together every group beyond `group_limit`. id: type: string description: >- Configured model ID for `model` series, agent profile ID for `profile` series. name: $ref: '#/components/schemas/ResourceName' description: >- Configured model or agent profile name, resolved even if it has since been deleted. Present with `id`. model_provider_config_name: $ref: '#/components/schemas/ResourceName' description: >- Name of the configured model's provider config, so same-named models can be told apart. Present on `model` series. project_name: $ref: '#/components/schemas/ResourceName' description: >- Name of the agent profile's project, so same-named profiles in different projects can be told apart. Present on `profile` series. total: type: number format: double minimum: 0 description: Metric over the whole window. values: type: array description: Metric in each bucket, aligned with `bucket_starts`. items: type: number format: double minimum: 0 Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. current_digest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- Current file digest for file_content_conflict or expected_digest_required; absent if the file no longer exists. A replacement must be confirmed before retrying with this digest. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. x-go-type: ErrorCode x-extensible-enum: - invalid_request - unauthorized - forbidden - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - gone - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited - internal_error - service_unavailable - idempotency_key_conflict - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. x-extensible-enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - idempotency_key_conflict - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. x-extensible-enum: - internal_error - service_unavailable - authentication_unavailable UsageTokenTotals: type: object additionalProperties: false description: >- Summed token counts across the tallied model calls. Input totals are the sum of uncached, cache-read, and cache-write tokens; output totals include reasoning tokens. required: - input_tokens_total - uncached_input_tokens - cache_read_input_tokens - cache_write_input_tokens - output_tokens_total - reasoning_output_tokens properties: input_tokens_total: type: integer format: int64 minimum: 0 uncached_input_tokens: type: integer format: int64 minimum: 0 cache_read_input_tokens: type: integer format: int64 minimum: 0 cache_write_input_tokens: type: integer format: int64 minimum: 0 output_tokens_total: type: integer format: int64 minimum: 0 reasoning_output_tokens: type: integer format: int64 minimum: 0 UsageCostTotals: type: object additionalProperties: false required: - provider_reported_usd - model_calls_with_reported_cost properties: provider_reported_usd: type: string description: >- Exact decimal sum in USD of the costs the provider reported for the tallied model calls. Calls whose provider reported no cost contribute nothing; compare model_calls_with_reported_cost against model_calls to see how complete the figure is. pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ model_calls_with_reported_cost: type: integer format: int64 minimum: 0 ResourceName: type: string minLength: 1 maxLength: 64 x-omnara-unicode-normalization: NFC description: >- Human-readable name. Spaces and punctuation are allowed; leading or trailing whitespace and invisible or control characters are not. AgentConfigErrorIssue: type: object additionalProperties: false required: - path - message properties: path: type: string description: >- JSON Pointer (RFC 6901) to the offending field in the submitted document. An empty string refers to the whole document. message: type: string description: Human-readable description of the problem with this field. line: type: integer minimum: 1 description: >- 1-based line of the offending field in the submitted source, when it can be located. column: type: integer minimum: 1 description: >- 1-based column of the offending field in the submitted source, when it can be located. parameters: UsageSince: name: since in: query required: false schema: type: string format: date-time description: >- Only tally model calls started at or after this instant. Omit to start from the earliest recorded call. UsageUntil: name: until in: query required: false schema: type: string format: date-time description: >- Only tally model calls started before this instant. Must be later than `since` when both are given. Omit to include calls up to now. responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service dependency required to satisfy the request is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' ClientError: description: >- Any other client error. The body carries the shared Error envelope restricted to client error codes; statuses with a dedicated response above are documented precisely. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ClientErrorCode' ServerError: description: >- Any other server error. The body carries the shared Error envelope restricted to server error codes. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ServerErrorCode' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Omnara personal or organization access token description: An opaque Omnara personal or organization bearer token. browserSessionCookie: type: apiKey in: cookie name: __Host-omnara_session description: >- Browser session cookie. HTTPS deployments use __Host-omnara_session; local HTTP development uses omnara_session. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.