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

Required permissions: account:users:read, billing:usage:read, auth:keys:read. Key presets that include them: BILLING, FULL. See key permissions.

GET

organization

billing-events

Organization Billing Events

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

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/organization/billing-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "billing_events": [
    {
      "username": "acme-ml-team",
      "request_id": "abc123",
      "endpoint_id": "fal-ai/flux/dev",
      "timestamp": "2025-01-15T10:30:45Z",
      "quantity": 2,
      "output_units": 2,
      "unit": "image",
      "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",
      "quantity": 1.5,
      "output_units": 1.5,
      "unit": "image",
      "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
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the BILLING preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_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

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

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

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

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

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

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

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

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

Hide child attributes

billing_events.username

string

required

Team username that generated this billing event

billing_events.request_id

string

required

Unique identifier for the request

billing_events.endpoint_id

string

required

Endpoint identifier that was used (e.g., 'fal-ai/flux/dev')

billing_events.timestamp

string

required

Request timestamp in ISO8601 format

billing_events.quantity

number | null

required

Billable units consumed, in the unit named by unit. Same value as the deprecated output_units.

Required range: x >= 0

billing_events.output_units

number | null

required

deprecated

Deprecated: use quantity. Same value as quantity.

Required range: x >= 0

billing_events.unit

string | null

required

The billing unit these units are counted in (e.g. 'image', 'second', 'megapixel'). Null when the reporter recorded none.

billing_events.unit_price

number | null

required

Per-unit price this line is measured against: the list rate when a discount is reported in percent_discount, otherwise the negotiated rate after any price override and before percentage discounts.

Required range: x >= 0

billing_events.percent_discount

number | null

required

Discount percentage applied to this request (e.g., 10 = 10% discount)

billing_events.cost_subtotal

number

required

Cost before discounts in USD (output_units × unit_price)

Required range: x >= 0

billing_events.cost_discount

number

required

Discount applied to this request in USD (cost_subtotal − cost_total)

Required range: x >= 0

billing_events.cost_total

number

required

Amount charged after discounts in USD (cost_subtotal − cost_discount)

Required range: x >= 0

billing_events.cost_estimate_nano_usd

number

required

Amount charged after discounts in nano USD. The precision-preserving representation of cost_total, not a legacy duplicate: an integer nano-USD amount avoids the float error that accumulates when summing sub-cent charges (1 USD = 1,000,000,000 nano USD).

Required range: x >= 0

billing_events.auth_method

string

Authentication method label resolved across the organization (e.g., 'my-key (owner: acme-ml-team)', 'alice alice@example.com', or 'None'). Only populated when 'auth_method' is included in the expand parameter.

billing_events.auth_method_structured

object

Structured authentication method identity resolved across the organization. Only populated when 'auth_method_structured' is included in the expand parameter.

Hide child attributes

billing_events.auth_method_structured.detail

string

required

Human-readable summary of the authentication method (key alias, login username, or 'User token'/'None').

billing_events.auth_method_structured.api_key_id

string

API key ID, present when the request was made with an API key.

Team member login username (nickname), present when the request was made with a user login token resolvable to a team member.

⌘I

Organization Billing Events

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

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/organization/billing-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "billing_events": [
    {
      "username": "acme-ml-team",
      "request_id": "abc123",
      "endpoint_id": "fal-ai/flux/dev",
      "timestamp": "2025-01-15T10:30:45Z",
      "quantity": 2,
      "output_units": 2,
      "unit": "image",
      "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",
      "quantity": 1.5,
      "output_units": 1.5,
      "unit": "image",
      "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
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}