---
title: "Retrieve your organization's API usage and spend over time"
method: GET
path: "/v2/account/usage"
tags: ["account"]
---

# Retrieve your organization's API usage and spend over time

`GET /v2/account/usage`

Returns your organization's billed API usage as dense time buckets of
line items. Every line item carries the billed dollar amount; products
billed per item also carry `billed_units` (unit, quantity, and unit
price, where `quantity × unit_price = cost_total`). Usage-priced
products (billed by metered provider usage) report `cost_total` only.

Buckets cover the requested range completely — a bucket with no line
items means no billed usage in that window. Line items are unique per
bucket on (`product`, `dimensions`, `api_key.id`, unit price). Usage
billed without an API key (requests authenticated as a user session)
is included with `api_key` absent, so totals always reconcile with
your invoices.
`product` and `endpoint` are stable identifiers safe to aggregate on;
`description` is display text and may be reworded at any time.

Usage data may lag live traffic by a few minutes, and responses may be
cached briefly, so this endpoint is for reporting rather than
real-time monitoring.

Requires an API key whose owner is an organization admin. Keys owned
by other members receive a 404.

## Query parameters

- `start_time` string, date-time, required
- `end_time` string, date-time
- `bucket_width` '1d' | '1h'
- `sources` string[]

## Response `200`

Bucketed usage for the requested range.

- GetAccountUsageResponse
  - `buckets` AccountUsageBucket[], required — Dense, chronological buckets covering the requested range.
    - `start_time` string, date-time, required — Start of the bucket window (inclusive, UTC).
    - `end_time` string, date-time, required — End of the bucket window (exclusive, UTC).
    - `line_items` AccountUsageLineItem[], required — Usage billed in this window. Empty when nothing was billed.
      - `product` string, required — Stable identifier of the public pricing catalog entry this charge was billed under, at the granularity the pricing page prices it (for example one entry per quality and resolution). `unknown` when a historical charge can no longer be attributed; its cost is still included.
      - `endpoint` string, required — The API endpoint path this product belongs to.
      - `description` string, required — Name of the public pricing catalog entry, as shown on the pricing page. Not an identifier.
      - `dimensions` object — Pricing dimensions this line item was billed under, for products priced per dimension (for example rendering speed).
      - `cost_total` string, required — Total billed amount in `currency_code`, as a decimal string.
      - `currency_code` string, required — ISO 4217 currency code of the amounts on this line item.
      - `source` 'api' | 'app', required — Which billing surface the usage came through. `api` usage is attributed to an API key when one was used; `app` usage is attributed to the member who generated it.
      - `api_key` AccountUsageApiKey — The API key the usage was billed to, in redacted form.
        - `id` string, required — The API key's id, as listed by `GET /v2/account/api-keys`.
        - `redacted_key` string, nullable — The first characters of the key followed by bullets.
        - `label` string, nullable — The key's user-supplied label, when one is set.
      - `user_email` string, nullable — Email address of the member who generated the usage. Only present on `app` usage.
      - `billed_units` AccountUsageBilledUnits — Per-unit detail for products billed per item. `quantity × unit_price` always equals the line item's `cost_total`.
        - `unit` string, required — What one billed unit is (for example `image`).
        - `quantity` string, required — Number of units billed, as a decimal string.
        - `unit_price` string, required — Price per unit in `currency_code`, as a decimal string.

## Other responses

- `400` — Invalid time range, bucket width, or filters.
- `401` — Unauthorized.
- `404` — No organization with billing access was found for this credential.
- `429` — Too many requests.

## Changes

- **2026-09-10** `185ac0b0801d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/changes/v2/account/usage/get.md)

---

[API](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0.md) · [All operations](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/llms.txt) · [OpenAPI document](https://skmtc.dev/ideogram/apis/ideogram-openapi-3-0/revisions/52c1c6497d87?raw)