FAfal
Account

FOCUS Report

Changed on

Returns a FOCUS compliant billing report as a CSV download.

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

Supports three data sources:

  • invoice: Finalized invoice data for a billing month. Includes usage charges, credits, and taxes.
  • estimate: Real-time usage estimates for a date range. Pre-invoice data that may change once invoiced.
  • tagged-estimate: Those same estimates with the Tags column populated from the X-Fal-Tags tags set on your requests. Requires tagged reporting to be enabled for the account; recent usage is delayed relative to estimate.

The report follows the FinOps FOCUS specification for cloud billing data interoperability.

Invoice reports default to the most recently available billing month. Usage estimates default to the last 24 hours, with a maximum 90-day date range.

Organization roots may pass expand=organization to report the whole organization — each team as a BillingAccount, plus per-team SubAccount attribution under shared (pooled) billing. Without it, the report is single-account, and the estimate covers only the calling account. Note: under pooled billing the invoice source already spans all pooled teams even without expand (they share one billing customer); expand=organization adds the per-team SubAccount breakdown.

Required permissions: billing:usage:read, auth:keys:read, account:users:read. Key presets that include them: BILLING, FULL. See key permissions.

get/account/focus

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/account/focus
  • Auth
    API key in header Authorization

Query parameters

source'invoice' | 'estimate' | 'tagged-estimate' required

Report source. 'invoice' returns finalized invoice data for a billing month. 'estimate' returns real-time usage estimates for a date range. 'tagged-estimate' returns those same estimates with the Tags column populated from the X-Fal-Tags tags set on your requests; it requires tagged reporting to be enabled for the account, and recent usage is delayed relative to 'estimate'.

Example:invoice
billing_monthstring

Billing month (YYYY-MM) — selects invoices by their issue date (when the invoice was issued). Used with source=invoice. Defaults to the current billing month.

Example:2025-02
charge_monthstring

Charge month (YYYY-MM) — selects line items by the period charges were incurred, capturing them even when split across invoices issued in different months. Alternative to billing_month. Used with source=invoice.

Example:2025-01
expand'organization'

Expand the report to the whole organization. Only valid for an organization root; each team is reported as a BillingAccount and, under shared (pooled) billing, per-team SubAccount attribution is added. Omit for a single-account report.

Example:organization
string date-time
OR
string
string date-time
OR
string
timezonestring

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

Example:UTC
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).

Example:day
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.

Example:true

Response

FOCUS compliant CSV report

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security billingApiKey was added to the API

    • info

      the endpoint scheme security adminApiKey was removed from the API

  • 0c7dabf80b00Revision changes
    • info

      added the new enum value tagged-estimate to the query request parameter source