---
title: "Billing Events"
method: GET
path: "/models/billing-events"
tags: ["Models", "Usage"]
---

# Billing Events

`GET /models/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](https://fal.ai/docs/documentation/model-apis/faq) for more details.

## Query parameters

- `limit` integer — Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
- `cursor` string — Pagination cursor from previous response. Encodes the page number.
- `start` union — Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
  - string, date-time
  - string
- `end` union — 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.
  - string, date-time
  - string
- `endpoint_id` union — 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
  - string
  - string[]
- `request_id` union — 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
  - string
  - string[]
- `api_key_id` union — 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
  - string
  - string[]
- `login_username` union — 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
  - string
  - string[]
- `expand` union — 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).
  - string
  - string[]

## Response `200`

Billing event data retrieved successfully

- object — Response containing billing event data with pagination support
  - `next_cursor` string, nullable, 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
    - `request_id` string, required — Unique identifier for the request
    - `endpoint_id` string, required — Endpoint identifier that was used (e.g., 'fal-ai/flux/dev')
    - `timestamp` string, required — Request timestamp in ISO8601 format
    - `output_units` number, nullable, required — Custom billing units for this request
    - `unit_price` number, nullable, required — Unit price for this request
    - `percent_discount` number, nullable, required — Discount percentage applied to this request (e.g., 10 = 10% discount)
    - `cost_subtotal` number, required — Cost before discounts in USD (output_units × unit_price)
    - `cost_discount` number, required — Discount applied to this request in USD (cost_subtotal − cost_total)
    - `cost_total` number, required — Amount charged after discounts in USD (cost_subtotal − cost_discount)
    - `cost_estimate_nano_usd` number, required — Amount charged after discounts in nano USD — the same charge as cost_total (1 USD = 1,000,000,000 nano USD)
    - `auth_method` string — Authentication method label (e.g., 'Key 1', 'API Key', 'User token'). Only populated when 'auth_method' is included in expand parameter.
    - `auth_method_structured` object — Structured authentication method identity. Only populated when 'auth_method_structured' is included in expand parameter.
      - `detail` string, required — Human-readable summary of the authentication method (key alias, login username, or 'User token'/'None').
      - `api_key_id` string — API key ID, present when the request was made with an API key.
      - `login_username` string — Team member login username (nickname), present when the request was made with a user login token resolvable to a team member.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `403` — Access denied
- `404` — Resource not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/fal/apis/platform-apis.md) · [All operations](https://skmtc.dev/fal/apis/platform-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fal/platform-apis/revisions/0c7dabf80b00/schema)