Organization Usage
get_organization_usageRetrieve paginated organization-wide usage records across all teams and fal product lines, filtered by team, product, API key, endpoint, and date range.
Instructions
Returns paginated usage records across all teams and product lines in your
organization, with each record attributed to a specific team via the
username field and a product line via the product field.
Covers all three fal product lines:
model_apis— model API endpoint calls (e.g.fal-ai/flux/dev)serverless— fal Serverless SDK billingcompute— fal Compute (raw instance time)
Availability: This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.
Must be called with an admin API key on the organization's root team.
Key Features:
Organization-wide usage data across all teams and products
Filter by team(s) (
team_username), product line (product), endpoint, API key (api_key_id), date range, and auth methodPer-team and per-product attribution on every usage record
Paginated time series and aggregate summary views
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' for a resolved authentication method label, and 'auth_method_structured' for 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. | |
| product | No | Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute). | |
| 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 | |
| team_username | No | Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams. | |
| 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 |