Sign in
Organization

Organization Billing Events

Returns paginated individual billing event records across all teams in your organization, with each record attributed to a specific team via the username field. Each record includes a per-request cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD).

Scoped to fal Model API billing events. Must be called with an admin API key on the organization's root team.

Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.

Key Features:

  • Organization-wide model-API billing event records across all teams
  • Filter by team(s) (team_username), endpoint, API key (api_key_id), request ID, and date range
  • Per-team attribution and per-request cost breakdown on every record
  • Cursor-based pagination for efficient large dataset queries
  • Limited to 100 records per page for performance
  • Date range capped at 90 days per request

See fal.ai docs for more details.

get/organization/billing-events

Query parameters

limitinteger

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Example:50

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==

Pagination cursor from previous response. Encodes the page number.

string date-time
OR
string

Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.

string date-time
OR
string

End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.

string
OR
string[]

Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2

string
OR
string[]

Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2

string
OR
string[]

Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2

string
OR
string[]

Filter billing events by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns billing events across all teams.

string
OR
string[]

Data to include in the response. Use 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username).

Response

Organization billing event data retrieved successfully

next_cursorstring nullable required

Cursor for the next page of results, null if no more pages

has_moreboolean required

Boolean indicating if more results are available (convenience field derived from next_cursor)

Changes

No recorded changes to this endpoint across all 2 revisions of this API.