Organization FOCUS Report

Returns a FOCUS compliant billing report as a CSV download, spanning every team in your organization. Each invoiced billing customer is reported as a BillingAccount. Under shared (pooled) billing — one billing customer covering multiple teams — each row is additionally attributed to the calling team via the SubAccountId / SubAccountName columns. SubAccountId is that team’s own billing customer ID, so both account columns share one identifier namespace.

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

Must be called with a key on the organization’s root team.

Supports three data sources:

estimate: Real-time usage estimates for a date range. Under pooled billing every row is attributed to the calling team.
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 organization; recent usage is delayed relative to estimate.
invoice: Finalized invoice data for a billing month. Under pooled billing, per-team SubAccount attribution is available on endpoint (Model API) lines that carry a caller; app and compute lines carry no caller and have no SubAccount.

Use team_username to restrict the report to a single team. Under shared (pooled) billing this is rejected for source=invoice — the invoice is issued to one billing customer shared across teams and cannot be split per team; use source=estimate for per-team figures.

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.

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

GET

organization

focus

Organization FOCUS Report

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

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/organization/focus', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<string>

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the BILLING preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Query Parameters

source

enum<string>

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 organization, and recent usage is delayed relative to 'estimate'.

Available options:

invoice,

estimate,

tagged-estimate

Example:

"estimate"

billing_month

string

Invoice billing month (YYYY-MM). The month the invoice was issued (e.g. '2025-02' for January charges). Used with source=invoice. Defaults to most recent available billing month.

Pattern: ^\d{4}-\d{2}$

Example:

"2025-02"

charge_month

string

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.

Pattern: ^\d{4}-\d{2}$

Example:

"2025-01"

team_username

string

Restrict the report to a single team (workspace nickname) in the organization. Omit to report across all teams.

Example:

"acme-ml-team"

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"

Response

FOCUS compliant CSV report

The response is of type string.

⌘I

Organization FOCUS Report

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

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/organization/focus', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<string>

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}