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 [e-mail] 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

Organization Billing Events

cURL

curl --request GET \
  --url https://api.fal.ai/v1/organization/billing-events \
  --header 'Authorization: <api-key>'

200

{
  "billing_events": [
    {
      "username": "acme-ml-team",
      "request_id": "abc123",
      "endpoint_id": "fal-ai/flux/dev",
      "timestamp": "2025-01-15T10:30:45Z",
      "output_units": 2,
      "unit_price": 0.025,
      "percent_discount": 10,
      "cost_subtotal": 0.05,
      "cost_discount": 0.005,
      "cost_total": 0.045,
      "cost_estimate_nano_usd": 45000000
    },
    {
      "username": "acme-research",
      "request_id": "def456",
      "endpoint_id": "fal-ai/flux/dev",
      "timestamp": "2025-01-15T10:25:30Z",
      "output_units": 1.5,
      "unit_price": 0.025,
      "percent_discount": null,
      "cost_subtotal": 0.0375,
      "cost_discount": 0,
      "cost_total": 0.0375,
      "cost_estimate_nano_usd": 37500000
    }
  ],
  "next_cursor": "MjAyNS0wMS0xNVQxMDoyNTozMFp8ZGVmNDU2",
  "has_more": true
}

Authorizations

Authorization · string · header · required

Admin API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_ADMIN_API_KEY

Query Parameters

limit · integer

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

Required range: x >= 1

Example:

50

cursor · string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

start · string<date-time> string

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

Example:

"2025-01-01T00:00:00Z"

end · string<date-time> 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.

Example:

"2025-02-01T00:00:00Z"

endpoint_id · string 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

Example:

["fal-ai/flux/dev"]

request_id · string 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

Example:

["req-abc123"]

api_key_id · string 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

Example:

["abc123"]

team_username · string 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.

Example:

["acme-ml-team"]

expand · string 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).

Example:

"auth_method"

Response

200

application/json

Organization billing event data retrieved successfully

Response containing organization billing event data with pagination support

next_cursor · string | null · required

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

has_more · boolean · required

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

billing_events · object[] · required

List of billing event records with team attribution

Show child attributes