fal.ai

fal now limits how often you can list, inspect, shell into, stop, and kill apps and runners. The limits apply to the CLI, the Python SDK, and the REST API. When you exceed a limit, the REST API returns 429 Too Many Requests, and the CLI and SDK return the gRPC status RESOURCE_EXHAUSTED. Learn more about the limits

Admins can now assign two new team roles. Creator can use the Playground, Sandbox, and Workflows, but cannot view request logs or manage API keys, billing, members, or roles. Viewer has read-only access to team resources. A Viewer can view request logs and the library, but cannot run models or change anything. Existing members keep their current roles. Learn more about team roles

Keys now use permission presets instead of the ADMIN and API scopes. When you create a key, select one of seven presets: API, SERVERLESS, DEPLOY, COMPUTE, BILLING, READONLY, or FULL. If no preset matches your case, select the exact permissions the key needs. You can also limit a key to specific models and set it to expire. A preset key follows the live definition of its preset. A custom policy key, including a preset key with a model limit, keeps the permissions it had at creation. Existing ADMIN and API keys continue to work. The Platform API reference now lists the permissions each API requires and the presets that include them. Learn more about key permissions

Shared WebSocket endpoints can now declare billing on their 101 upgrade response. Set x-fal-billable-units when the unit count is known at connect time. Set x-fal-billable-units-webhook to 1 when the count is only known at the end of the session. Then report the total with POST /requests/billable-units/{request_id}. The platform still charges sessions without either header by duration. Learn more about billable units

Deployed Serverless apps now include Testing > Playground in the app dashboard. Select an available endpoint, fill in its generated input form, and run a request without leaving the app. Multi-endpoint apps have one place to test their endpoints, using the existing Playground authentication and billing behavior. Open the guide

A batch of endpoints rounds out programmatic access to what the dashboard shows about your serverless apps: GET /v1/serverless/apps — list your deployed apps with live state: active runners, queue size, machine types, and environment. Add expand=endpoints to include each app's route-level endpoint ids, in the exact form the requests and analytics APIs accept. GET /v1/serverless/apps/{owner}/{name}/events — operational event history: deployments, configuration changes, and runner lifecycle transitions — the "what changed around this time?" API. Also surfaced in the dashboard's events timeline. GET /v1/serverless/apps/{owner}/{name}/revisions — revision history with deployment status, who deployed, and deploy messages and annotations (the API behind the August 3 entry above) — line revision boundaries up against your error timeline to spot a bad deploy. GET /v1/serverless/apps/{owner}/{name}/runners/history — historical runner counts by state (running, idle, pending, draining) for capacity analysis and incident forensics. Together with the existing requests, logs, analytics, metrics, and usage APIs, these power the new Platform MCP server — and they're plain REST endpoints you can call directly with your API key.

fal's second MCP server — the Platform API MCP — is now available at https://api.fal.ai/v1/mcp/platform. Where the Run MCP lets your AI assistant *build with models*, this one lets it *operate your fal account*: connect Claude Code, Cursor, or any MCP-compatible client with your API key and ask *"why did my last request to my-app fail?"* — your assistant walks the same debugging steps you would. *15 tools: eleven first-class serverless debugging tools covering requests, logs, error analytics, deploy and revision history, runner and queue state, spend, and persistent storage — plus a four-tool discovery gateway that opens up the rest of the Platform API (compute, workflows, keys, account, organization, storage) without bloating your assistant's context. claude mcp add --transport http fal-platform \ https://api.fal.ai/v1/mcp/platform \ --header "Authorization: Key YOUR_FAL_KEY" Read-only — it can observe your account but never change it; write operations are listed in the catalog but refuse to execute Stateless — your key is sent per-request and never stored, and normal permission and ownership scoping applies Free — tool calls are the same Platform API calls you could make directly with your key Setup guide →

Runner telemetry now includes a dedicated GPU Utilization chart alongside the existing CPU, memory, and VRAM charts, so you can see how much compute your GPUs are actually doing -- not just how much memory they hold. GPU Utilization reports the average compute utilization across a runner's GPUs over time, surfaced both as a current stat and a time-series chart in the runner side sheet. Pair it with VRAM Usage to tell a memory-bound runner apart from a compute-bound one, making it easier to right-size machine types and spot under-utilized GPUs. Open any runner from the Runners page (Dashboard → Apps → \[your-app] → Runners) to view its telemetry. See Runner Analytics for details.

The BILLING key preset is now read-only for billing. A key on this preset can read usage, invoices, contracts, and billing settings. It can no longer change payment methods or billing settings. The preset now also grants read access to the list of keys and to the model catalog. The READONLY preset no longer grants request sharing. A key on a preset follows the live definition of that preset, so existing BILLING and READONLY keys picked up these changes at their next request. If the permissions of a key must stay the same for the life of the key, create the key with a custom policy. See Key permissions.

You can now attach a freeform message and custom annotations to each revision when deploying: fal deploy my_app.py::MyApp --message "Deploying new version" --annotation GIT_SHA=a1b2c3d4 Messages and annotations are set at deploy time and stay with the revision. View and search them on the app's Versions page in the dashboard, or fetch them via the revisions API. Also available in the Python SDK: client.deploy(..., message=..., annotations={...}). See Annotating Deployments for details.

Apps can now register a default per-condition retry budget at deploy time with the new retry_config deployment option, using the same format as the X-Fal-Retry-Config request header. Set it as a class attribute on fal.App or under the app's table in pyproject.toml. Applies to all queue-based requests to the app; the app owner can still override it per-request with the X-Fal-Retry-Config header. Each condition (server_error, timeout, connection_error) keeps an independent budget, bounded by the platform ceiling of 10 total attempts. See Retries and Error Handling for details.

The new Serverless Usage page (Serverless → Usage) provides attributable, dimensioned reporting of serverless compute spend in the dashboard. Compute reported in machine-seconds, broken down per app, environment, and machine type. Spend is split by price category: Reserve, Burst, On-Demand, and List. This distinguishes consumption covered by committed reserved capacity from burst overage and undiscounted list-rate usage, supporting reservation sizing and workload placement decisions. Group by app or by machine type, including a dedicated Usage by machine type view, to identify the deployments and hardware classes driving cost. Billing-cycle and custom time-range presets are supported. On-demand quotes are reported as a distinct price category, and organization-level reporting now spans both serverless and compute. This is the same dataset returned by the GET /v1/serverless/usage API, surfaced in the dashboard.

The Usage & Billing page has been rebuilt to support usage attribution (the Settings "Overview" tab is now "Usage"). Filter by auth method, API key, and login username to attribute consumption to a specific credential or user. Normalized app names and revised charts improve readability and export.

Existing Docker-based servers (ComfyUI, custom APIs) can now be deployed without rewriting them as a fal.App, reducing migration effort from self-hosted infrastructure, Kubernetes, or RunPod. Direct Server Mode: set exposed_port in pyproject.toml and fal routes traffic directly to the container port. Existing routes, middleware, and response formats are preserved. Prebuilt image references (no Dockerfile required): reference an image already pushed to a registry (image = "my-org/my-server:latest") and override entrypoint/cmd under [tool.fal.apps. .image]. Private registry support: pull from Docker Hub, Google Artifact Registry, or Amazon ECR by supplying registry credentials in the image configuration. Migration guides are available for external Docker servers and RunPod, along with the pyproject.toml reference and Private Docker Registries.

New GET /v1/serverless/usage endpoint reports your own serverless compute usage — the machine-seconds each of your deployed apps consumed, priced with your machine rates and net of discounts Break usage down per app, environment, and machine type, with time_series and summary views over any date range and timeframe Filter by app name with app (exact, one or more) or search (case-insensitive substring) — match a deployed app by name without needing its exact version suffix Ideal for per-app cost reporting and exporting to your own billing/observability tools Complements the per-request billable_units on GET /v1/serverless/requests/by-endpoint with an aggregated, time-bucketed view

The new Capacity page (Serverless → Capacity) reports GPU consumption against your account limit, providing visibility into available headroom before requests begin queuing. Account-wide GPU usage over time, plotted against your limit, with baseline and burst reference lines indicating utilization relative to reserved capacity. Per-GPU-type breakdown of capacity consumption by hardware class. Approaching-limit and at-limit indicators on runner and app views, with GPU counts shown on runners. Request more capacity action for requesting a higher limit.

The new X-Fal-Retry-Config request header replaces all-or-nothing retry behavior with a separate retry budget per failure condition, allowing retry policy to be tuned independently for each failure mode. Map each retry condition (server_error, timeout, connection_error) to its own retries count (for example, retry transient server errors while disabling retries on timeouts). Each condition maintains an independent budget, bounded by the platform ceiling of 10 total attempts. Applies to apps you own and takes precedence over status-code defaults. x-fal-no-retry takes precedence when both are set. Complements app-level skip_retry_conditions and the per-response X-Fal-Needs-Retry and x-fal-stop-runner controls. See Retries and Error Handling for the full reference.

Managing a large number of serverless apps is now easier with new filtering and sorting controls directly on the apps page. Filter by machine type to instantly isolate apps running on specific hardware (e.g., H100, A100, L40) and monitor targeted resource allocation. Sort by active runners, GPUs, or queue size to instantly surface the apps consuming the most capacity or backing up with queued requests. Works in both card view and list view, and stacks with environment and tag filtering so you can find what needs your attention faster.

The GET /v1/models/analytics and GET /v1/serverless/analytics endpoints now support fourteen additional metrics via the expand parameter, matching the metric families the dashboard surfaces: Error type breakdown — startup_error_count, connection_error_count, timeout_error_count, runtime_error_count for finer-grained failure attribution beyond the existing 4xx/5xx counts Cold boot metrics — cold_boot_count, p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration for tracking startup latency Extended latency percentiles — p25_duration, p95_duration, p99_duration, p95_prepare_duration, p99_prepare_duration for tail-latency analysis Total billable duration — total_billable_duration for aggregate billable execution time (the sum of request execution durations) Existing metrics and response shape are unchanged; only new optional fields are added.