Your organization's generation usage, by API: every generation and charge across all workspaces, with credits, models, members and projects.
Endpoint GET https://fnf-api-gw.higgsfield.ai/fnf/v1/organization/generation_usage_report
Get an API key
The organization owner creates keys in Settings → Usage → Team usage → API keys → Add.
A key is shown only once, so copy it and store it on your server. Choose when it expires: 30 days, 90 days or 1 year.
Keys can only read usage data.
Revoking a key stops it immediately. To rotate, create a new key, deploy it, then revoke the old one.
Headers
x-api-key: your API key. Call the API from your server and never hardcode the key; the examples read it from HIGGSFIELD_ORG_KEY.
User-Agent: a name for your integration, for example acme-usage-sync/1.0.
Parameters
Parameters
Parameter
Rules
starting_at
Required. Window start, inclusive: RFC 3339 with an offset, at most microsecond precision (2026-10-01T00:00:00Z). Not before 2026-02-01T00:00:00Z and not in the future.
ending_at
Optional. Window end, exclusive, in the same format: after starting_at and at most 31 days later; may be in the future. Default: the earlier of now and starting_at + 31 days.
limit
Optional. Rows per page, 1–1000 (default 1000).
page
The previous response's next_page. Keep starting_at and ending_at the same.
The generation id (UUID), or chg_… for a charge row.
type
string
generation or charge.
created_at
RFC 3339, milliseconds
When the generation was created; for a charge row, the time of its earliest deduction.
workspace_id, workspace_name
UUID; string
The row's workspace or sub-workspace, deleted ones included. The name is the current one; "" when there is none.
actor
object
{"type": "user_actor", "user_id", "email_address"}. user_id is a person or a service account. email_address is the current email; null when there is none.
model, model_name
string
The stable model key and its display name.
credits
decimal string
Two decimals, e.g. "12.50"; parse as a decimal. Credits charged inside the window, net of refunds; "0.00" when nothing was charged.
status
string or null
The generation's status. Final: completed, failed, canceled, nsfw, ip_detected. Other current values, such as waiting, queued or in_progress, mean it isn't final yet. null on a charge row.
generation_id
UUID or null
The row's generation; null for a charge with no generation, such as chat.
original_generation_id
UUID or null
For a copy, the generation it was originally copied from; otherwise null.
projects
array
[{"id", "name"}]: the projects of the row's workspace that hold the generation, sorted by id; [] when none.
chat_id
UUID or null
The Supercomputer chat the row came from, or null.
New values of type, status and model can appear; handle values you don't know.
Good to know
Pages: repeat the request with page=<next_page> while has_more is true. Rows are sorted by created_at, then id.
Rows: one per generation created in the window, plus charge rows for charges in the window not tied to one of its generations, such as chat. A charge row totals one charge's credit deductions for one model in the window; its created_at, actor, generation_id and chat_id come from the earliest deduction.
Keeping a copy: the data is live, and refunds can reduce previously reported credits. Read fixed UTC windows (days or months) that never overlap. When every page of a window has succeeded, replace your stored copy of that window, keyed by id. Re-read recent windows.
Limits: 60 requests a minute and 2 at a time per organization, across all its keys.
Errors Errors are JSON: {"type": "error", "error": {"type", "code", "message", "param"}, "request_id"}. Send the request_id to support. If an error isn't JSON, send support its response headers and the time of the request.