Skip to main content
GET
/
organization
/
usage
Organization Usage
curl --request GET \
  --url https://api.fal.ai/v1/organization/usage \
  --header 'Authorization: <api-key>'
{
  "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"
        },
        {
          "username": "acme-ml-team",
          "product": "compute",
          "endpoint_id": "type: gpu_1x_h100_sxm5 (my-app, production)",
          "unit": "second",
          "quantity": 3600,
          "unit_price": 0.001,
          "cost": 3.6,
          "currency": "USD"
        }
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Authorizations

​
Authorization
string
header
required

Admin API key must be prefixed with "Key ", e.g. Authorization: Key YOUR_ADMIN_API_KEY

Query Parameters

​
limit
integer

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

Required range: x >= 1
Example:

50

​
cursor
string

Pagination cursor from previous response. Encodes the page number.

Example:

"Mg=="

​
start

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

Example:

"2025-01-01T00:00:00Z"

​
end

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.

Example:

"2025-02-01T00:00:00Z"

​
timezone
string
default:UTC

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

Example:

"UTC"

​
timeframe
enum<string>

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

Available options:
minute,
hour,
day,
week,
month
Example:

"day"

​
bound_to_timeframe
enum<string>
default: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.

Available options:
true,
false
Example:

"true"

​
endpoint_id

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

Example:
["fal-ai/flux/dev"]
​
team_username
string

Filter by a specific team username within the organization. If not provided, returns usage across all teams.

Example:

"acme-ml-team"

​
product

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

Example:
["model_apis", "compute"]
​
expand
default:["time_series"]

Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, and 'auth_method' to include authentication method information. At least one of 'time_series' or 'summary' is required.

Example:
["time_series", "auth_method"]

Response

Organization usage data retrieved successfully

Response containing organization usage data with pagination support

​
next_cursor
string | null
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.

​
summary
object[]

Aggregate statistics (when expand includes 'summary')