--- title: "Usage" method: GET path: "/models/usage" tags: ["Models", "Usage"] --- # Usage `GET /models/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](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 - `timezone` string — Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. - `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). - `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. - `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[] - `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 '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. - string - string[] ## Response `200` Usage data retrieved successfully - object — Response containing usage 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) - `time_series` object[] — Time series usage data grouped by time bucket (when expand includes 'time_series'). Each bucket contains all usage records for that time period. - `bucket` string, required — Time bucket timestamp in user's timezone with offset (ISO8601 datetime) - `results` object[], required — Usage records for this time bucket - `endpoint_id` string, required — Endpoint identifier that was used (e.g., 'fal-ai/flux/dev') - `unit` string, required — The billing unit (e.g., 'image', 'video', or a GPU/compute unit for some models) - `quantity` number, required — Quantity of usage in the specified billing unit - `unit_price` number, required — Per-unit price before percentage discounts - `percent_discount` number, nullable, required — Percentage discount applied to this line item (e.g., 20 = 20% discount). Null when no percentage discount applies. Usage billed at different discount rates appears as separate rows, like unit_price. - `cost_subtotal` number, required — Cost before discounts (quantity × unit_price) - `cost_discount` number, required — Discount applied to this line item (cost_subtotal − cost_total) - `cost_total` number, required — Amount charged after discounts (cost_subtotal − cost_discount) - `cost` number, required — Deprecated: use cost_total. Same value as cost_total. - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD') - `auth_method` string — Authentication method label (e.g., 'Key 1', 'Key 2', '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. - `summary` object[] — Aggregate statistics (when expand includes 'summary') - `endpoint_id` string, required — Endpoint identifier that was used (e.g., 'fal-ai/flux/dev') - `unit` string, required — The billing unit (e.g., 'image', 'video', or a GPU/compute unit for some models) - `quantity` number, required — Quantity of usage in the specified billing unit - `unit_price` number, required — Per-unit price before percentage discounts - `percent_discount` number, nullable, required — Percentage discount applied to this line item (e.g., 20 = 20% discount). Null when no percentage discount applies. Usage billed at different discount rates appears as separate rows, like unit_price. - `cost_subtotal` number, required — Cost before discounts (quantity × unit_price) - `cost_discount` number, required — Discount applied to this line item (cost_subtotal − cost_total) - `cost_total` number, required — Amount charged after discounts (cost_subtotal − cost_discount) - `cost` number, required — Deprecated: use cost_total. Same value as cost_total. - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD') - `auth_method` string — Authentication method label (e.g., 'Key 1', 'Key 2', '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 - `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)