Skip to main content
GET
cURL
This endpoint is in beta and is enabled per organization. Contact support to request access or share feedback. Calls from an organization without access return a 404. The response shape can change while the endpoint is in beta.organization_id is optional in beta but will be required at GA, so send it now to avoid a breaking change.
This endpoint returns usage for the API key’s entire organization, not only the key’s project. Any project’s key can read it, including keys created by external collaborators, and access can’t be restricted to organization admins. When project-scoped keys start enforcing their scope, you will need to swap the key you use here for one with organization-level access. Usage data for the current month can be up to 1 hour behind. Data for prior months can be up to 24 hours behind. When reading line items:
  • product_name values are display names, not stable identifiers, and can change without notice.
  • attributes vary by product. For example, api_key_id and project_id are only set on inference line items.

Authorizations

Authorization
string
header
default:default
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

month
string

Billing month in YYYY-MM format. Defaults to the current month, which returns data through yesterday (daily) or the last completed hour (hourly).

Pattern: ^\d{4}-(0[1-9]|1[0-2])$
organization_id
string

Organization to report on. Usage is always reported for the organization that owns the API key, so this is optional; supplying an ID that is not that organization returns 403.

Minimum string length: 1
granularity
enum<string>
default:day

Time window size for rows. 'hour' returns ~24x more rows than 'day'.

Available options:
day,
hour
limit
integer
default:100

Maximum number of time windows per page (max 1000).

Required range: 1 <= x <= 1000
after
string

Opaque cursor from a previous response's next_cursor. Only valid for the month and granularity it was issued for. Current-month data is a moving snapshot: each page reflects data as of its request, so newly completed windows may appear at the end of the sequence.

Response

Billing usage report for the requested month

object
string
required
Allowed value: "list"
organization_id
string
required

ID of the organization the report belongs to.

billing_period
string
required

Billing month (YYYY-MM).

earliest_window_start
string<date-time> | null
required

Start of the earliest time window with usage in the month (UTC, ISO 8601); null when the month has no usage.

latest_window_end
string<date-time> | null
required

Exclusive end of the latest time window with usage in the month (UTC, ISO 8601); null when the month has no usage. Describes the whole month, not the current page.

currency
string
required
Allowed value: "USD"
data
object[]
required

Time windows containing usage line items.

next_cursor
string | null
required

Opaque cursor for the next page; null when this is the last page.