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

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.

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",
      "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
    },
    {
      "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": "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

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

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

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

Show child attributes

⌘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",
      "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
    },
    {
      "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": "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"
  }
}