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.

GET

models

billing-events

Billing Events

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

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

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

{
  "billing_events": [
    {
      "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
    },
    {
      "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": "MjAyNS0wMS0xNVQxMDoyNTozMFo=",
  "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"
  }
}

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"

source

enum<string>

default: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'.

Available options:

billed,

tagged-billed

Example:

"billed"

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"]

tag

Filter by X-Fal-Tags 'key=value' pairs. Accepts 1-10 filters: different keys are AND-combined (?tag=env=prod&tag=team=design), and repeating a key matches any of its values. Use the value '(untagged)' to match requests that did not set the key.

Example:

["env=prod"]

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"]

login_username

Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob

Example:

["alice"]

expand

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

Example:

"auth_method"

Response

Billing event data retrieved successfully

Response containing 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

Hide child attributes

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 (e.g., 'Key 1', 'API Key', 'User token'). Only populated when 'auth_method' is included in expand parameter.

billing_events.auth_method_structured

object

Structured authentication method identity. Only populated when 'auth_method_structured' is included in 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.

billing_events.tags

object

Activated X-Fal-Tags key/values set on this request. Only populated when source=tagged-billed; a key the request did not set is omitted, so a request that set none reports {}.

Hide child attributes

billing_events.tags.{key}

string

⌘I

Billing Events

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

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

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

{
  "billing_events": [
    {
      "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
    },
    {
      "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": "MjAyNS0wMS0xNVQxMDoyNTozMFo=",
  "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"
  }
}