fal Release Notes

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.

Platform MCP Server

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.

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

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.

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.

GPU Utilization in Runner Telemetry

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.

Deploy Messages and Annotations

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.

New Serverless Usage Page

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.

Deploy Existing Docker Servers Without Code Changes

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.