---
title: "Analytics"
method: GET
path: "/models/analytics"
tags: ["Models", "Analytics"]
---

# Analytics

`GET /models/analytics`

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](https://fal.ai/docs/documentation/model-apis/inference/queue) 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
- `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.
- `endpoint_id` union, required — 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[]
- `expand` union — Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required.
  - string
  - string[]

## Response `200`

Analytics data retrieved successfully

- object — Response containing performance analytics 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 analytics data grouped by time bucket (when expand includes 'time_series'). Each bucket contains all analytics records for that time period.
    - `bucket` string, required — Time bucket timestamp in user's timezone with offset (ISO8601 datetime)
    - `results` object[], required — Analytics records for this time bucket
      - `endpoint_id` string, required — Endpoint identifier for these statistics
      - `request_count` integer — Total number of requests
      - `success_count` integer — Number of successful requests (2xx responses)
      - `user_error_count` integer — Number of user errors (4xx responses)
      - `error_count` integer — Number of server errors (5xx responses)
      - `p50_prepare_duration` number — 50th percentile queue/prepare time before execution in seconds
      - `p75_prepare_duration` number — 75th percentile queue/prepare time before execution in seconds
      - `p90_prepare_duration` number — 90th percentile queue/prepare time before execution in seconds
      - `p95_prepare_duration` number — 95th percentile queue/prepare time before execution in seconds
      - `p99_prepare_duration` number — 99th percentile queue/prepare time before execution in seconds
      - `p50_duration` number — 50th percentile request execution duration in seconds
      - `p75_duration` number — 75th percentile request execution duration in seconds
      - `p90_duration` number — 90th percentile request execution duration in seconds
      - `p25_duration` number — 25th percentile request execution duration in seconds
      - `p95_duration` number — 95th percentile request execution duration in seconds
      - `p99_duration` number — 99th percentile request execution duration in seconds
      - `startup_error_count` integer — Number of startup errors (startup timeout, scheduling failure)
      - `connection_error_count` integer — Number of connection errors (connection timeout, disconnected, refused)
      - `timeout_error_count` integer — Number of request timeout errors
      - `runtime_error_count` integer — Number of runtime errors (internal error, server error)
      - `cold_boot_count` integer — Number of requests with cold boot (startup time > 1 second)
      - `p50_cold_boot_duration` number — 50th percentile cold boot duration in seconds (only cold starts)
      - `p75_cold_boot_duration` number — 75th percentile cold boot duration in seconds (only cold starts)
      - `p90_cold_boot_duration` number — 90th percentile cold boot duration in seconds (only cold starts)
      - `total_billable_duration` number — Total billable execution duration in seconds (sum of all request durations)
  - `summary` object[] — Aggregate statistics (when expand includes 'summary')
    - `endpoint_id` string, required — Endpoint identifier for these statistics
    - `request_count` integer — Total number of requests
    - `success_count` integer — Number of successful requests (2xx responses)
    - `user_error_count` integer — Number of user errors (4xx responses)
    - `error_count` integer — Number of server errors (5xx responses)
    - `p50_prepare_duration` number — 50th percentile queue/prepare time before execution in seconds
    - `p75_prepare_duration` number — 75th percentile queue/prepare time before execution in seconds
    - `p90_prepare_duration` number — 90th percentile queue/prepare time before execution in seconds
    - `p95_prepare_duration` number — 95th percentile queue/prepare time before execution in seconds
    - `p99_prepare_duration` number — 99th percentile queue/prepare time before execution in seconds
    - `p50_duration` number — 50th percentile request execution duration in seconds
    - `p75_duration` number — 75th percentile request execution duration in seconds
    - `p90_duration` number — 90th percentile request execution duration in seconds
    - `p25_duration` number — 25th percentile request execution duration in seconds
    - `p95_duration` number — 95th percentile request execution duration in seconds
    - `p99_duration` number — 99th percentile request execution duration in seconds
    - `startup_error_count` integer — Number of startup errors (startup timeout, scheduling failure)
    - `connection_error_count` integer — Number of connection errors (connection timeout, disconnected, refused)
    - `timeout_error_count` integer — Number of request timeout errors
    - `runtime_error_count` integer — Number of runtime errors (internal error, server error)
    - `cold_boot_count` integer — Number of requests with cold boot (startup time > 1 second)
    - `p50_cold_boot_duration` number — 50th percentile cold boot duration in seconds (only cold starts)
    - `p75_cold_boot_duration` number — 75th percentile cold boot duration in seconds (only cold starts)
    - `p90_cold_boot_duration` number — 90th percentile cold boot duration in seconds (only cold starts)
    - `total_billable_duration` number — Total billable execution duration in seconds (sum of all request durations)

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