Usage
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
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.
Query parameters
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
Pagination cursor from previous response. Encodes the page number.
Pagination cursor from previous response. Encodes the page number.
Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
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.
Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
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).
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).
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.
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.
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
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
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
Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required.
Response
Usage data retrieved successfully