Usage

Time-bucketed, aggregated serverless compute usage for your own account — the machine-seconds your deployed serverless apps consumed, priced with your machine prices and net of discounts. This matches the serverless portion of the dashboard usage view. Unlike /v1/models/usage (which reports your model API endpoint calls), this reports the compute spend of the apps you run on fal Serverless. Results are always scoped to the apps you own.

Requires an ADMIN-scoped API key — this endpoint returns billing and usage data, which the standard API key scope does not include.

Filtering by app:

app — exact match on one or more app names (comma-separated or repeated, up to 50): ?app=my-app-dev,my-app-prod. Use the value exactly as it appears in the response app field.
search — case-insensitive substring match on the app name, for when you know the name but not the exact environment/version suffix: ?search=my-app returns every my-app* variant.
Provide both to AND them. Omit both to return every app you own — useful for discovering the exact app names to filter on.

Expansions:

time_series: usage grouped into time buckets (default)
summary: a single aggregate row per app × machine type across the window

Notes:

Each row is machine-seconds (unit is always "second"); surge and non-surge usage of the same app/machine come back as separate rows (is_surge), so sum across them for a per-app total.
Time-series bucket timestamps are returned in the timezone you request (ISO 8601 with offset, e.g. 2025-01-15T00:00:00-05:00), which also controls how usage is grouped into buckets.

Common Use Cases:

Track your serverless apps’ compute consumption and cost over time
Break down spend per app, environment, and machine type
Export usage to your own billing/observability tooling

GET

serverless

usage

Usage

curl --request GET \
  --url https://api.fal.ai/v1/serverless/usage \
  --header 'Authorization: <api-key>'

{
  "time_series": [
    {
      "bucket": "2025-01-15T00:00:00-05:00",
      "results": [
        {
          "app": "my-app-prod",
          "environment": null,
          "machine_type": "GPU-H100",
          "unit": "second",
          "quantity": 1200,
          "unit_price": 0.00099,
          "cost": 1.188,
          "currency": "USD",
          "is_surge": false
        }
      ]
    }
  ],
  "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"

app

Filter to one or more serverless apps, matched exactly against the app value in the response (deployed name, owner prefix stripped). Accepts a comma-separated list or repeated parameter (1-50). For partial/name-only matching use search.

Example:

["autohdr-raw-to-jpg-dev"]

string

Case-insensitive substring match on the app name — returns every app whose name contains this term (e.g. search=autohdr matches all autohdr-* apps across environments). Combined with app via AND when both are given.

Example:

"autohdr-raw-to-jpg"

expand

default:["time_series"]

Data to include in the response. Use 'time_series' for time-bucketed data and 'summary' for aggregate statistics across the entire window. At least one is required.

Example:

["time_series", "summary"]

Response

Usage data retrieved successfully

Response containing serverless 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').

Show child attributes

summary

object[]

Aggregate statistics (when expand includes 'summary')

Show child attributes

List Requests by EndpointLists requests for one or more endpoints owned by the authenticated user. Use repeated or comma-separated `endpoint_id` (same as other platform list APIs). **Authentication:** Requires API key. **Filters:** - Time range via start / end. If `start` is omitted, defaults to the last 24 hours — unless `request_id` is provided, in which case the default start bound is widened to 90 days. - Status (success, error, user_error) - Request ID - Pagination via cursor/limit (limit defaults to 50, max 100) **Sorting:** - By end time (default) or duration **Expansions:** - Include payloads by adding expand=payloads - Include per-request `billable_units` by adding expand=billing (endpoint owner only)

⌘I

Usage

curl --request GET \
  --url https://api.fal.ai/v1/serverless/usage \
  --header 'Authorization: <api-key>'

{
  "time_series": [
    {
      "bucket": "2025-01-15T00:00:00-05:00",
      "results": [
        {
          "app": "my-app-prod",
          "environment": null,
          "machine_type": "GPU-H100",
          "unit": "second",
          "quantity": 1200,
          "unit_price": 0.00099,
          "cost": 1.188,
          "currency": "USD",
          "is_surge": false
        }
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false
}