FAfal
Models
Usage

Usage

Changed on

Returns paginated usage records for your workspace with filters for endpoint, user, date range, and auth method. Each item includes the billed unit quantity, the pre-discount unit price and cost_subtotal, any percentage discount applied, and the final cost_total (cost_subtotal − cost_discount).

Key Features:

  • Usage data for all endpoints or filtered by specific endpoint(s)
  • Flexible date range filtering
  • User-specific usage tracking
  • Detailed usage line items with unit quantity, price, and discount breakdown
  • Paginated results for large datasets

Tagged usage: pass source=tagged-estimate to read the tagged aggregate instead of the default estimate. Each row then carries a tags object built from the X-Fal-Tags tags set on your requests, and tag=key=value filters narrow the results — repeat the parameter to AND several pairs together. Requires tagged reporting to be enabled for the account; recent usage is delayed relative to the default source.

Common Use Cases:

  • Generate usage reports for all endpoints or specific models
  • Track usage patterns
  • Monitor endpoint usage across different auth methods
  • Build usage dashboards and visualizations

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/usage

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/models/usage
  • 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
timezonestring

Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.

Example:UTC
timeframe'minute' | 'hour' | 'day' | 'week' | 'month'

Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).

Example:day
bound_to_timeframe'true' | 'false'

Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided.

Example:true
source'estimate' | 'tagged-estimate'

Data source. 'estimate' is the default usage estimate. 'tagged-estimate' reads the tagged aggregate instead, populating each row's 'tags' and enabling the 'tag' filter; it requires tagged reporting to be enabled for the account, and recent usage is delayed relative to 'estimate'.

Example:estimate
string
OR
string[]
string
OR
string[]
string
OR
string[]
string
OR
string[]
string
OR
string[]

Response

Usage 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

    • info

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