---
title: "Organization Billing Events"
method: GET
path: "/organization/billing-events"
tags: ["Organization"]
---

# Organization Billing Events

`GET /organization/billing-events`

Returns paginated individual billing event records across all teams in your
organization, with each record attributed to a specific team via the
`username` field. Each record includes a per-request cost breakdown in USD
(cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries
cost_total in nano USD).

Scoped to fal Model API billing events. Must be called with an admin API key on
the organization's root team.

> **Availability:** This endpoint is available to enterprise customers with organizations enabled. Contact your account team or support@fal.ai to request access.

**Key Features:**
- Organization-wide model-API billing event records across all teams
- Filter by team(s) (`team_username`), endpoint, API key (`api_key_id`), request ID, and date range
- Per-team attribution and per-request cost breakdown on every record
- Cursor-based pagination for efficient large dataset queries
- Limited to 100 records per page for performance
- Date range capped at 90 days per request

See [fal.ai docs](https://fal.ai/docs/documentation/model-apis/faq) 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
- `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[]
- `request_id` union — Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2
  - 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 billing events by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns billing events across all teams.
  - string
  - string[]
- `expand` union — Data to include in the response. Use '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).
  - string
  - string[]

## Response `200`

Organization billing event data retrieved successfully

- object — Response containing organization billing event 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)
  - `billing_events` object[], required — List of billing event records with team attribution
    - `username` string, required — Team username that generated this billing event
    - `request_id` string, required — Unique identifier for the request
    - `endpoint_id` string, required — Endpoint identifier that was used (e.g., 'fal-ai/flux/dev')
    - `timestamp` string, required — Request timestamp in ISO8601 format
    - `output_units` number, nullable, required — Custom billing units for this request
    - `unit_price` number, nullable, required — Unit price for this request
    - `percent_discount` number, nullable, required — Discount percentage applied to this request (e.g., 10 = 10% discount)
    - `cost_subtotal` number, required — Cost before discounts in USD (output_units × unit_price)
    - `cost_discount` number, required — Discount applied to this request in USD (cost_subtotal − cost_total)
    - `cost_total` number, required — Amount charged after discounts in USD (cost_subtotal − cost_discount)
    - `cost_estimate_nano_usd` number, required — Amount charged after discounts in nano USD — the same charge as cost_total (1 USD = 1,000,000,000 nano USD)
    - `auth_method` string — Authentication method label resolved across the organization (e.g., 'my-key (owner: acme-ml-team)', 'alice <alice@example.com>', or 'None'). Only populated when 'auth_method' is included in the expand parameter.
    - `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)