The Organization dashboard: credit spend by category, per-member stats, exportable reports, and the read-only organization API.
Open Organization to see where your workspace’s credits go. Use Usage to find a specific transaction or export a report.
View the workspace overview
Open Manage Account → Organization.
Review credit spending by category, generation counts, unique users, and models used. Top credit spenders shows spending by member; choose Show 5, 10, or 25 to change the list length.
Select Usage details to open Team usage for detailed workspace and member reporting.
Find a transaction
Open Manage Account → Usage and choose Personal usage or Team usage.
Select the date range and click Refresh when you need to reload the data.
In Personal usage, filter Usage history by feature and action: Spent, Refunded, or Granted.
In Team usage, filter by workspace, project, model, or user. Choose By credits or By generations to change the chart metric. Team usage requires the Access and export usage analytics permission.
Manage Account → Usage → Team usage → Usage by members → Export CSV
Cinema Studio project usage
Open the project, then Settings → Usage statistics → Export CSV
If Team usage or an export action is unavailable, ask the workspace Owner to check your permissions.
Review sub-workspace usage
Each sub-workspace has its own usage view. Use Team usage in the main workspace to include sub-workspaces in your reporting.
The Organization dashboard also shows pending credit requests. Follow Sub-Workspaces to approve or reject them.
Using the API
Read your organization’s usage report: every generation and charge across all workspaces, with credits, models, members and projects. With a Content key, also read each generation’s content: the member’s prompt, the media it took and the files it produced.
Endpoints:
GET https://fnf-api-gw.higgsfield.ai/fnf/v1/organization/generation_usage_report
GET https://fnf-api-gw.higgsfield.ai/fnf/v1/organization/generations
GET https://fnf-api-gw.higgsfield.ai/fnf/v1/organization/generations/{generation_id}
This section covers the read-only organization API for usage and existing generation content. To create images or videos programmatically, use the separate Higgsfield generation API, which has its own account, keys, and billing.
Get an API key
The organization owner creates keys in Settings → Usage → Team usage → API keys → Add.
Choose the key's permissions. They can't be changed later.
Usage (read:usage): the usage report.
Content (read:content): generations with members' prompts, inputs and files. Grant only to systems that should see members' work.
A key can have both permissions. Keys created before Content existed have Usage only; create a new key for Content.
Keys are shown once. Copy yours and store it on your server. Choose an expiry: 30 days, 90 days, 1 year or never.
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 from your server; never hardcode the key. Examples read it from HIGGSFIELD_ORG_KEY.
User-Agent: integration name, e.g. acme-usage-sync/1.0.
Usage report
GET /v1/organization/generation_usage_report requires a key with Usage.
Parameters
Parameters
Parameter
Rules
starting_at
Required. Inclusive window start: RFC 3339 with an offset and at most microsecond precision (2026-10-01T00:00:00Z). Not before 2026-02-01T00:00:00Z or in the future.
ending_at
Optional. Exclusive window end in the same format: after starting_at, at most 31 days later. May be in the future. Default: earlier of now and starting_at + 31 days.
limit
Optional. 1–1000 rows per page (default 1000).
page
The previous response's next_page. Keep starting_at, ending_at and filters unchanged.
user_ids[]
Optional. Only these users' rows (actor.user_id). Repeat for each user, up to 100.
models[]
Optional. Only these models' rows (model). Repeat for each model, up to 100.
states[]
Optional. Only generations in these states (state): queued, running, succeeded, failed, canceled. Excludes charge rows, which have no state. Repeat for each state.
A row must match at least one value of each supplied filter, e.g. &states[]=failed&states[]=canceled. Filtered pages can contain fewer than limit rows, including zero, before the last page. With cURL, use -g to send brackets unchanged.
Generation creation time; for charge rows, the earliest deduction time.
workspace_id, workspace_name
UUID; string
Workspace or sub-workspace, including deleted ones. Current name; "" if none.
actor
object
{"type": "user_actor", "user_id", "email_address", "name"}. user_id identifies a person or service account. email_address and name are current, or null if absent.
model, model_name
string
Stable model key and display name.
credits
decimal string
Two decimals, e.g. "12.50"; parse as a decimal. Credits charged within the window, net of refunds; "0.00" if nothing was charged.
credits_charged
decimal string
Same charges before refunds.
credits_refunded
decimal string
Refunds of those charges: credits_charged minus credits.
status
string or null
Generation status. Final: completed, failed, canceled, nsfw, ip_detected. Other current values, e.g. waiting, queued or in_progress, are not final. null on charge rows.
state
string or null
status mapped to five states: queued, running, succeeded, failed (includes nsfw and ip_detected), canceled. null on charge rows or for statuses not yet covered.
started_at
RFC 3339, milliseconds, or null
When the generation started running.
completed_at
RFC 3339, milliseconds, or null
When it succeeded; set only when state is succeeded.
failed_at
RFC 3339, milliseconds, or null
When it failed; set only when state is failed.
error
object or null
When state is failed: {"code", "message"}. code: content_moderated, ip_detected, timeout, invalid_input, provider_error, internal_error or generation_failed. message: short English message. Otherwise null.
generation_id
UUID or null
Row's generation; null for charges without a generation, such as chat.
original_generation_id
UUID or null
For a copy, the original source generation; otherwise null.
output_type
string or null
image, video, audio, 3d, text or data; null on charge rows or when unknown.
parameters
object or null
Requested duration (seconds), resolution, aspect_ratio, width and height (pixels), and batch_size (generations per request; each has its own row). Each is null when the generation has none; the object is null on a charge row.
source
object or null
surface, e.g. cinema_studio, mcp, claude_code, supercomputer or canvas (null for the Higgsfield app itself); client_name, the MCP client or creative app; cli_version, the Higgsfield CLI version. null on charge rows.
projects
array
[{"id", "name"}]: projects in the row's workspace containing the generation, sorted by id; [] if none.
chat_id
UUID or null
Source Supercomputer chat, or null.
New type, status, state, model, error.code, output_type and source.surface values can appear. Handle unknown values.
Generations and their content
Both endpoints require a key with Content.
GET /v1/organization/generations lists generations created in a window, with their content. It uses the usage report's parameters, with limit 1–100 (default 100). Large content can reduce the page size below limit; continue while has_more is true.
GET /v1/organization/generations/{generation_id} reads one generation.
Each generation includes all usage report fields and its content. In lists, credits covers charges within the window; for a single generation, all credits charged so far.
Examples
For cURL — download a file: set CONTENT_URL to a response's content_url.
GET /v1/organization/generations/0b6f2a4e-5c1d-4e8a-9f3b-2d7c6a1e9b40; lists return these objects in data with the usage report's page fields.
Content fields
Content fields
Field
Type
Values
deleted_at
RFC 3339, milliseconds, or null
Generation deletion time. Deleted generations have no content.
prompt
string or null
Prompt shown in the app: the member's prompt or, for some models, a version the app wrote from it, such as an enhanced prompt. Preset prompts are never shown.
negative_prompt
string or null
What the member asked the model to omit.
seed
integer or null
Requested seed.
inputs
array
Input media, in order: [{"id", "role", "source", "generation_id", "content_url"}]; [] if none.
inputs[].id
UUID or null
Upload ID or, for another generation's output, that generation's ID. Identical across generations using the media, though renditions can differ.
inputs[].role
string or null
Input role, e.g. image, start_image, end_image, video, audio, reference_image, or element for a reference element's media, such as a character's photos.
inputs[].source
string or null
upload for member uploads; generation for generation outputs.
inputs[].generation_id
UUID or null
Source generation when source is generation.
inputs[].content_url
string or null
Downloads the file this generation took; null if it can't be downloaded.
outputs
array
Output files, result first, then parts, such as clips or a grid's images: [{"size_bytes", "content_url", "thumbnail_url"}]; [] if no content.
outputs[].size_bytes
integer or null
File size in bytes.
outputs[].content_url
string
Downloads the file.
outputs[].thumbnail_url
string or null
Downloads the thumbnail; null if none.
New inputs[].role and inputs[].source values can appear.
Which generations have content
Content is available for generations the app shows to the organization owner among a member's assets. A generation must have succeeded, not be deleted, be of a kind the app lists (such as image, video or audio), and be in a workspace where the owner sees members' assets. Steps the app runs inside other generations, and generations in deleted sub-workspaces, have no content. Generations without content return only their row: prompt, negative_prompt and seed are null; inputs and outputs are []. Rarely, a visible generation also has no content.
Files
content_url and thumbnail_url require your key and return 302 with the file's address in Location.
Don't follow redirects with your key: most HTTP clients would forward it to the file's host. Read Location, then download that address without the key.
Download immediately and keep only content_url: the file's address can change.
Files are addressed by position within a generation. Download each input using its own content_url, even if another generation uses the same input id.
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. The usage report adds charge rows for charges in the window not tied to those generations, such as chat. Each charge row totals one charge's credit deductions for one model in the window; created_at, actor, generation_id and chat_id come from its earliest deduction.
Keeping a copy: data is live; refunds can reduce previously reported credits. Read fixed UTC windows (days or months) that never overlap. After all pages of a window succeed, replace your stored copy of that window, keyed by id. Re-read recent windows.
Limits: 60 requests per minute and 2 concurrent per organization, across all keys. File downloads count separately: 600 per minute and 4 concurrent.
Errors
Errors are JSON: {"type": "error", "error": {"type", "code", "message", "param"}, "request_id"}. Send request_id to support. For non-JSON errors, send support the response headers and request time.