Usage
get_usageRetrieve paginated workspace usage records filtered by endpoint, user, date range, or auth method to build cost reports, track patterns, and monitor API consumption.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | 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. | |
| limit | No | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. | |
| start | No | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. | |
| cursor | No | Pagination cursor from previous response. Encodes the page number. | |
| expand | No | 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. | |
| account | No | Exact private account key profile label, not an authenticated provider owner ID. | |
| timezone | No | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. | UTC |
| timeframe | No | 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). | |
| api_key_id | No | 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 | |
| endpoint_id | No | 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 | |
| login_username | No | 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 | |
| bound_to_timeframe | No | 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. | true |