---
title: "Organization Usage"
method: GET
path: "/organization/usage"
tags: ["Organization"]
---

# Organization Usage

`GET /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](https://fal.ai/docs/documentation) 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[]
- `team_username` union — 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
  - string[]
- `product` union — 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
  - string[]
- `expand` union — 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.
  - string
  - string[]

## Response `200`

Organization usage data retrieved successfully

- object — Response containing organization 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
      - `username` string, required — Team username within the organization — identifies which team incurred this line item.
      - `product` 'model_apis' | 'serverless' | 'compute', required — Product line the usage belongs to: 'model_apis' (fal Model APIs — endpoint calls), 'serverless' (fal Serverless SDK billing), or 'compute' (fal Compute — raw instances).
      - `endpoint_id` string, required — Identifier of the billed resource. For 'model_apis' this is the endpoint slug (e.g., 'fal-ai/flux/dev'); for 'serverless' it is the SDK billing line; for 'compute' it is the machine type line (e.g., 'type: gpu_1x_h100_sxm5 (my-app, prod)').
      - `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 — Unit price used to compute charges for this line item
      - `cost` number, required — Computed cost (quantity × unit_price)
      - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD')
      - `auth_method` string — Authentication method label resolved across the organization (e.g., 'my-key (owner: alice)', 'alice <alice@example.com>', or 'None'). Only populated when 'auth_method' is included in the expand parameter. Falls back to the raw upstream label if the decoration service cannot resolve a row.
      - `auth_method_structured` object — Structured authentication method identity resolved across the organization. Only populated when 'auth_method_structured' is included in the 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')
    - `username` string, required — Team username within the organization — identifies which team incurred this line item.
    - `product` 'model_apis' | 'serverless' | 'compute', required — Product line the usage belongs to: 'model_apis' (fal Model APIs — endpoint calls), 'serverless' (fal Serverless SDK billing), or 'compute' (fal Compute — raw instances).
    - `endpoint_id` string, required — Identifier of the billed resource. For 'model_apis' this is the endpoint slug (e.g., 'fal-ai/flux/dev'); for 'serverless' it is the SDK billing line; for 'compute' it is the machine type line (e.g., 'type: gpu_1x_h100_sxm5 (my-app, prod)').
    - `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 — Unit price used to compute charges for this line item
    - `cost` number, required — Computed cost (quantity × unit_price)
    - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD')
    - `auth_method` string — Authentication method label resolved across the organization (e.g., 'my-key (owner: alice)', 'alice <alice@example.com>', or 'None'). Only populated when 'auth_method' is included in the expand parameter. Falls back to the raw upstream label if the decoration service cannot resolve a row.
    - `auth_method_structured` object — Structured authentication method identity resolved across the organization. Only populated when 'auth_method_structured' is included in the 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
- `404` — Resource not found
- `429` — Rate limit exceeded
- `500` — Internal server error

---

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