FAfal
Models
Analytics

Analytics

Changed on

Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. prepare_duration reflects queue/prepare time before execution; duration is request execution time. Use with the Queue/Webhooks flow to monitor SLAs.

Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer.

Available Metrics:

The expand parameter accepts these values, grouped by category:

Volume

  • request_count: Total number of requests in the time bucket
  • success_count: Successful requests (2xx responses)
  • user_error_count: User errors (4xx responses)
  • error_count: Server errors (5xx responses)

Error type breakdown

  • startup_error_count: Startup errors (startup timeout, scheduling failure)
  • connection_error_count: Connection errors (timeout, disconnected, refused)
  • timeout_error_count: Request timeout errors
  • runtime_error_count: Runtime errors (internal error, server error)

Queue / prepare latency

  • p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts

Request execution latency

  • p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request

Cold boot

  • cold_boot_count: Requests with cold boot (startup > 1s)
  • p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles

Billing

  • total_billable_duration: Aggregate billed execution time

Key Features:

  • Selective metric inclusion via expand parameter
  • Performance metrics (latency percentiles, duration stats)
  • Reliability metrics (success/error rates, request counts)
  • Error type breakdown (startup, connection, timeout, runtime)
  • Cold boot metrics (count, latency percentiles)
  • Billing duration tracking
  • Time-bucketed data for trend analysis
  • Single or multi-model analytics
  • Flexible date range and timeframe options

Common Use Cases:

  • Monitor model performance and reliability
  • Generate performance dashboards
  • Analyze latency trends and patterns
  • Track error rates and success metrics

See Queue API docs for more details.

Required permissions: models:metrics:read. Key presets that include them: API, SERVERLESS, READONLY, FULL. See key permissions.

get/models/analytics

Request

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

Query parameters

limitinteger

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Example:50
cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==
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
string required
OR
string[] required
string
OR
string[]

Response

Analytics data retrieved successfully

next_cursorstring nullable required

Cursor for the next page of results, null if no more pages

has_moreboolean required

Boolean indicating if more results are available (convenience field derived from next_cursor)

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security readonlyApiKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API