Sign in
Organization

Organization Usage

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 billing
  • compute — 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 method
  • Per-team and per-product attribution on every usage record
  • Paginated time series and aggregate summary views

See fal.ai docs for more details.

get/organization/usage

Query parameters

limitinteger

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Example:50

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==

Pagination cursor from previous response. Encodes the page number.

string date-time
OR
string

Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.

string date-time
OR
string

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.

timezonestring

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

Example:UTC

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).

Example:day

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.

Example:true

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.

string
OR
string[]

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
OR
string[]

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
OR
string[]

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.

string
OR
string[]

Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute).

string
OR
string[]

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.

Response

Organization 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)

Example response

{
  "time_series": [
    {
      "bucket": "2025-01-15T00:00:00-05:00",
      "results": [
        {
          "username": "acme-ml-team",
          "product": "model_apis",
          "endpoint_id": "fal-ai/flux/dev",
          "unit": "image",
          "quantity": 4,
          "unit_price": 0.1,
          "cost": 0.4,
          "currency": "USD",
          "auth_method": "production-key (owner: acme-ml-team)"
        }
      ]
    }
  ],
  "summary": [
    {
      "username": "acme-ml-team",
      "product": "model_apis",
      "endpoint_id": "fal-ai/flux/dev",
      "unit": "image",
      "quantity": 4,
      "unit_price": 0.1,
      "cost": 0.4,
      "currency": "USD",
      "auth_method": "production-key (owner: acme-ml-team)"
    }
  ]
}

Changes