---
title: "Usage"
method: GET
path: "/serverless/usage"
tags: ["Serverless", "Usage"]
---

# Usage

`GET /serverless/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 model API
endpoint calls), this reports the `sdk_billing_event` compute spend of the apps
you run on fal Serverless. Requires an `ADMIN`-scoped API key (this endpoint
returns billing and usage data, which the standard `API` key scope does not
include); results are always scoped to the apps you own.

**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

## 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.
- `app` union — 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`.
  - string
  - string[]
- `search` 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.
- `expand` union — 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.
  - string
  - string[]

## Response `200`

Usage data retrieved successfully

- object — Response containing serverless 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').
    - `bucket` string, required — Time bucket timestamp in user's timezone with offset (ISO8601 datetime)
    - `results` object[], required — Usage records for this time bucket
      - `app` string, nullable, required — Deployed serverless app name (the billing owner prefix is stripped, e.g. 'autohdr-raw-to-jpg-dev'). May include an environment/version suffix. Null for line items without an app attribution.
      - `environment` string, nullable, required — Deployment environment of the app (e.g., 'production') when present on the billing line item, null otherwise.
      - `machine_type` string, required — Machine type the usage ran on (e.g., 'GPU-H100', 'L')
      - `unit` string, required — The billing unit — always 'second' (machine-seconds)
      - `quantity` number, required — Quantity of usage in the specified billing unit
      - `unit_price` number, required — Per-second price for this machine type before percentage discounts, including any customer-specific machine pricing
      - `percent_discount` number, nullable, required — Percentage discount applied to this line item (e.g., 20 = 20% discount). Null when no percentage discount applies. Usage billed at different discount rates appears as separate rows, like unit_price.
      - `cost_subtotal` number, required — Cost before discounts (quantity × unit_price)
      - `cost_discount` number, required — Discount applied to this line item (cost_subtotal − cost_total)
      - `cost_total` number, required — Amount charged after discounts (cost_subtotal − cost_discount)
      - `cost` number, required — Deprecated: use cost_total. Same value as cost_total.
      - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD')
      - `is_surge` boolean, required — Whether this usage was billed at surge pricing. Surge and non-surge usage of the same machine type appear as separate rows.
  - `summary` object[] — Aggregate statistics (when expand includes 'summary')
    - `app` string, nullable, required — Deployed serverless app name (the billing owner prefix is stripped, e.g. 'autohdr-raw-to-jpg-dev'). May include an environment/version suffix. Null for line items without an app attribution.
    - `environment` string, nullable, required — Deployment environment of the app (e.g., 'production') when present on the billing line item, null otherwise.
    - `machine_type` string, required — Machine type the usage ran on (e.g., 'GPU-H100', 'L')
    - `unit` string, required — The billing unit — always 'second' (machine-seconds)
    - `quantity` number, required — Quantity of usage in the specified billing unit
    - `unit_price` number, required — Per-second price for this machine type before percentage discounts, including any customer-specific machine pricing
    - `percent_discount` number, nullable, required — Percentage discount applied to this line item (e.g., 20 = 20% discount). Null when no percentage discount applies. Usage billed at different discount rates appears as separate rows, like unit_price.
    - `cost_subtotal` number, required — Cost before discounts (quantity × unit_price)
    - `cost_discount` number, required — Discount applied to this line item (cost_subtotal − cost_total)
    - `cost_total` number, required — Amount charged after discounts (cost_subtotal − cost_discount)
    - `cost` number, required — Deprecated: use cost_total. Same value as cost_total.
    - `currency` string, required — Three-letter currency code (ISO 4217, e.g., 'USD')
    - `is_surge` boolean, required — Whether this usage was billed at surge pricing. Surge and non-surge usage of the same machine type appear as separate rows.

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