Billing Events
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.
Authorizations
Query Parameters
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'.
billed, tagged-billed "billed"
Response
Billing event data retrieved successfully
Response containing billing event data with pagination support