FAfal
Models
Usage

Billing Events

Changed on

Returns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD).

Key Features:

  • Individual billing event records for each API request
  • Per-request cost breakdown before and after discounts
  • Flexible date range filtering
  • Optional endpoint filtering
  • Cursor-based pagination for efficient large dataset queries
  • Limited to 10000 records per page for performance
  • Date range capped at 90 days per request

Tagged billing events: pass source=tagged-billed to read the tagged billing-event pivot instead of the default feed. Each row then carries a tags object built from the X-Fal-Tags tags set on that request, and tag=key=value filters narrow the results — repeating the parameter with different keys ANDs them, repeating one key matches any of its values. Requires tagged reporting to be enabled for the account; recent events are delayed relative to the default source.

Common Use Cases:

  • Audit individual billing events
  • Track request patterns and volumes
  • Debug specific requests by ID
  • Monitor billing unit consumption per request

See fal.ai docs for more details.

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

get/models/billing-events

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/models/billing-events
  • Auth
    API key in header Authorization

Query parameters

limitinteger

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

Example:50
cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==
string date-time
OR
string
string date-time
OR
string
source'billed' | 'tagged-billed'

Data source. 'billed' is the default billed-event feed. 'tagged-billed' reads the tagged billing-event pivot instead, populating each row's 'tags' and enabling the 'tag' filter; it requires tagged reporting to be enabled for the account, and recent events are delayed relative to 'billed'.

Example:billed
string
OR
string[]
string
OR
string[]
string
OR
string[]
string
OR
string[]
string
OR
string[]
string
OR
string[]

Response

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

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security billingApiKey was added to the API

    • info

      the endpoint scheme security adminApiKey was removed from the API

  • f458dd367b3aRevision changes
    • info

      added the new optional query request parameter source

    • info

      added the new optional query request parameter tag

    • info

      added the optional property // to the response with the status