Sign in
account

Retrieve your organization's API usage and spend over time

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.

get/v2/account/usage

Query parameters

start_timestring date-time required

Start of the reporting range (RFC 3339). Snapped down to the containing bucket boundary (UTC).

end_timestring date-time

End of the reporting range (RFC 3339), exclusive. Snapped up to the next bucket boundary (UTC). Defaults to now.

bucket_width'1d' | '1h'

Bucket granularity. 1d allows ranges up to 92 days per request; 1h allows up to 168 hours. Page through longer histories by moving start_time back across successive requests.

sourcesstring[]

Which billing sources to include. api is usage from API requests; app is web-app usage, attributed to the member who generated it. Defaults to both, so report totals reconcile with invoices.

Response

Bucketed usage for the requested range.

Example response

{
  "buckets": [
    {
      "start_time": "2000-01-23T04:56:07+00:00",
      "end_time": "2000-01-23T04:56:07+00:00",
      "line_items": [
        {
          "product": "ideogram_v4_generation",
          "endpoint": "/v2/image/generate/ideogram-4",
          "cost_total": "84.00",
          "user_email": "user_email",
          "api_key": {
            "redacted_key": "ATG5•••••••••••••",
            "id": "JRPVD7jWR1aTBYiJ0UFVOg",
            "label": "Live production environment"
          },
          "description": "Ideogram v4 Generation",
          "billed_units": {
            "unit": "image",
            "quantity": "2100",
            "unit_price": "0.04"
          },
          "source": "api",
          "currency_code": "USD",
          "dimensions": {
            "key": "dimensions"
          }
        },
        {
          "product": "ideogram_v4_generation",
          "endpoint": "/v2/image/generate/ideogram-4",
          "cost_total": "84.00",
          "user_email": "user_email",
          "api_key": {
            "redacted_key": "ATG5•••••••••••••",
            "id": "JRPVD7jWR1aTBYiJ0UFVOg",
            "label": "Live production environment"
          },
          "description": "Ideogram v4 Generation",
          "billed_units": {
            "unit": "image",
            "quantity": "2100",
            "unit_price": "0.04"
          },
          "source": "api",
          "currency_code": "USD",
          "dimensions": {
            "key": "dimensions"
          }
        }
      ]
    },
    {
      "start_time": "2000-01-23T04:56:07+00:00",
      "end_time": "2000-01-23T04:56:07+00:00",
      "line_items": [
        {
          "product": "ideogram_v4_generation",
          "endpoint": "/v2/image/generate/ideogram-4",
          "cost_total": "84.00",
          "user_email": "user_email",
          "api_key": {
            "redacted_key": "ATG5•••••••••••••",
            "id": "JRPVD7jWR1aTBYiJ0UFVOg",
            "label": "Live production environment"
          },
          "description": "Ideogram v4 Generation",
          "billed_units": {
            "unit": "image",
            "quantity": "2100",
            "unit_price": "0.04"
          },
          "source": "api",
          "currency_code": "USD",
          "dimensions": {
            "key": "dimensions"
          }
        },
        {
          "product": "ideogram_v4_generation",
          "endpoint": "/v2/image/generate/ideogram-4",
          "cost_total": "84.00",
          "user_email": "user_email",
          "api_key": {
            "redacted_key": "ATG5•••••••••••••",
            "id": "JRPVD7jWR1aTBYiJ0UFVOg",
            "label": "Live production environment"
          },
          "description": "Ideogram v4 Generation",
          "billed_units": {
            "unit": "image",
            "quantity": "2100",
            "unit_price": "0.04"
          },
          "source": "api",
          "currency_code": "USD",
          "dimensions": {
            "key": "dimensions"
          }
        }
      ]
    }
  ]
}

Changes