Using the API — Enterprise Help Center

Your organization's generation usage, by API: every generation and charge across all workspaces, with credits, models, members and projects.

Using the API — Enterprise Help Center

Your organization's generation usage, by API: every generation and charge across all workspaces, with credits, models, members and projects.

EndpointGET https://fnf-api-gw.tavoa.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 TAVOA AI_ORG_KEY.

User-Agent: a name for your integration, for example acme-usage-sync/1.0.

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.

Examples

Example response

Response fields

Field

Type

Values

data

array

The rows of this page, described below.

has_more, next_page

boolean; string or null

has_more is true exactly when next_page is set.

organization_id

UUID

The key's organization.

starting_at, ending_at

RFC 3339, microseconds

The resolved window.

generated_at

RFC 3339, milliseconds

When this page was produced.

Each row:

id

string

The generation id (UUID), or chg_… for a charge row.

type

generation or charge.

created_at

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

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

For a copy, the generation it was originally copied from; otherwise null.

projects

[{"id", "name"}]: the projects of the row's workspace that hold the generation, sorted by id; [] when none.

chat_id

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.

ErrorsErrors 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.

Status

Code

What to do

400

invalid_parameter, missing_parameter, unknown_parameter, duplicate_parameter, invalid_range, before_data_start, invalid_page

Fix the request; param names the parameter.

api_key_in_url

The key was sent in the URL: revoke it, create a new one, and send keys only in x-api-key.

401

missing_api_key, invalid_api_key

Send a valid key.

403

missing_scope, organization_not_eligible

The key or the organization can't use this endpoint; ask your organization owner.

404, 405

not_found, method_not_allowed

Check the path and the method.

410

page_expired

Restart the window from its first page.

429

rate_limited, concurrent_request

Wait Retry-After seconds, then retry the same page.

500

internal_error

Retry the same page with backoff, a few times; if it persists, contact support.

report_limit_exceeded

Don't retry: a smaller limit or window won't help. Keep your stored copy and contact support.

503

overloaded

504

timeout

Retry the same page with backoff, a few times.