FAfal
Organization

Organization Usage

Changed on

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

Required permissions: account:users:read, billing:usage:read, auth:keys:read. Key presets that include them: BILLING, FULL. See key permissions.

get/organization/usage

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/organization/usage
  • Auth
    API key in header Authorization

Query parameters

limitinteger

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

Example:50
cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==
string date-time
OR
string
string date-time
OR
string
timezonestring

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

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

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,
          "percent_discount": 20,
          "cost_subtotal": 0.4,
          "cost_discount": 0.08,
          "cost_total": 0.32,
          "cost": 0.32,
          "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,
      "percent_discount": 20,
      "cost_subtotal": 0.4,
      "cost_discount": 0.08,
      "cost_total": 0.32,
      "cost": 0.32,
      "currency": "USD",
      "auth_method": "production-key (owner: acme-ml-team)"
    }
  ]
}

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security billingApiKey was added to the API

    • info

      the endpoint scheme security adminApiKey was removed from the API

  • 04f815c7612bRevision changes
    • info

      response property summary/items/cost deprecated

    • info

      response property time_series/items/results/items/cost deprecated

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property // to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status

    • info

      added the required property //// to the response with the status