Unified endpoint for discovering model endpoints. Supports three usage modes:

1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata.

2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs.

3. Search Mode (search parameters): Filter models by free-text query, category, or status.

Expansion: Use expand to include additional data in each model object:

• openapi-3.0 — full OpenAPI 3.0 schema in the openapi field

• enterprise_status — enterprise readiness status (ready or pending) in the enterprise_status field

Examples of endpoint_id values:

• fal-ai/flux/dev

• fal-ai/wan/v2.2-a14b/text-to-video

• fal-ai/minimax/video-01/image-to-video

• fal-ai/hunyuan3d-v21

See fal.ai Model APIs for more details.

Authentication: Optional. Providing an API key grants higher rate limits.

Common Use Cases:

• Browse available models for integration

• Retrieve metadata for specific endpoints

• Search for models by category or keywords

• Get OpenAPI schemas for code generation

• Build model selection interfaces

Returns unit pricing for requested endpoint IDs. Most models use output-based pricing (e.g., per image/video with proportional adjustments for resolution/length). Some models use GPU-based pricing depending on architecture. Values are expressed per model's billing unit in a given currency.

Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.

Common Use Cases:

• Display pricing in user interfaces

• Compare pricing across different models

• Build cost estimation tools

• Check current billing rates

See fal.ai pricing for more details.

Computes cost estimates using one of two methods:

1. Historical API Price (historical_api_price):

• Based on historical pricing per API call from past usage patterns

• Takes call_quantity (number of API calls) per endpoint

• Useful for estimating based on actual historical usage patterns

• Example: "How much will 100 calls to flux/dev cost?"

2. Unit Price (unit_price):

• Based on unit price × expected billing units from pricing service

• Takes unit_quantity (number of billing units like images/videos) per endpoint

• Useful when you know the expected output quantity

• Example: "How much will 50 images from flux/dev cost?"

Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status.

Common Use Cases:

• Pre-calculate costs for batch operations

• Display cost estimates in user interfaces

• Budget planning and cost optimization

See fal.ai pricing for more details.

Returns paginated usage records for your workspace with filters for endpoint, user, date range, and auth method. Each item includes the billed unit quantity, the pre-discount unit price and cost_subtotal, any percentage discount applied, and the final cost_total (cost_subtotal − cost_discount).

Key Features:

• Usage data for all endpoints or filtered by specific endpoint(s)

• Flexible date range filtering

• User-specific usage tracking

• Detailed usage line items with unit quantity, price, and discount breakdown

• Paginated results for large datasets

Common Use Cases:

• Generate usage reports for all endpoints or specific models

• Track usage patterns

• Monitor endpoint usage across different auth methods

• Build usage dashboards and visualizations

See fal.ai docs for more details.

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.

Returns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD).

Key Features:

• Individual billing event records for each API request

• Per-request cost breakdown before and after discounts

• Flexible date range filtering

• Optional endpoint filtering

• Cursor-based pagination for efficient large dataset queries

• Limited to 10000 records per page for performance

• Date range capped at 90 days per request

Common Use Cases:

• Audit individual billing events

• Track request patterns and volumes

• Debug specific requests by ID

• Monitor billing unit consumption per request

See fal.ai docs for more details.

Deletes the IO payloads and associated CDN output files for a specific request.

Important:

• Only output CDN files are deleted (input files may be used by other requests)

• This action is irreversible

• Requires authentication with an admin API key

What gets deleted:

• Request input/output payload data

• CDN-hosted output files (images, videos, etc.)

What is NOT deleted:

• Input CDN files (may be referenced by other requests)

Response:

• Returns deletion status for each CDN file

• Each result includes the file link and any error that occurred

Idempotency:

• Optional Idempotency-Key header prevents duplicate deletions on retries

• Responses cached for 10 minutes per unique key

See fal.ai docs for more details about request payloads.

Lists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs).

Authentication: Requires API key (user or enterprise).

Filters:

• Time range via start / end. If start is omitted, defaults to the last 24 hours — unless request_id is provided, in which case the default start bound is widened to 90 days.

• Status (success, error, user_error)

• Request ID

• Pagination via cursor/limit (limit defaults to 50, max 100)

Sorting:

• By end time (default) or duration

Expansions:

• Include payloads by adding expand=payloads

Search, filter, and browse your request history. Supports three modes:

1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search.

2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first).

3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity.

Filter Options:

• endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs)

• exclude_api_requests / only_api_requests: Filter by request source

Examples:

• Semantic text search: ?query=sunset+landscape

• Image similarity: ?image_url=https://...&min_similarity=0.5

• Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev

• Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell

List workflows for the authenticated user with optional search and filtering.

Features:

• Paginated results with cursor-based pagination

• Search by workflow name or title

• Filter by model endpoints used in the workflow

Authentication: Required. Returns only workflows owned by the authenticated user.

Common Use Cases:

• Display user's workflow library

• Search for specific workflows

• Find workflows using particular models

Create a new workflow owned by the authenticated user.

Authentication: Required.

Common Use Cases:

• Save a newly built workflow

• Programmatically provision workflows

Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.

Get detailed information about a specific workflow, including its full contents/definition.

Authentication: Required.

Common Use Cases:

• Load a workflow for editing

• View workflow configuration

• Export workflow definition

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

List asset collections for the authenticated user's fal Assets library.

Create asset collection for the authenticated user's fal Assets library.

Get asset collection for the authenticated user's fal Assets library.

Update asset collection for the authenticated user's fal Assets library.

Delete asset collection for the authenticated user's fal Assets library.

Get the nested subtree rooted at an asset collection, plus its ancestor collections ordered from the top level down to its direct parent.

Favorite an asset collection for the authenticated user's fal Assets library.

Unfavorite an asset collection for the authenticated user's fal Assets library.

Move a manual asset collection under another collection, or to the top level. Only manual collections can be moved or act as folders; nesting is limited to 5 levels deep and cannot create a cycle.

Browse assets in a collection for the authenticated user's fal Assets library.

Add an asset to a manual or character collection. Provide a request ID or vector ID; unresolved references are materialized before local collection state is added. For character collections, the asset is added by applying the character tag.

Remove an asset from a manual or character collection by request ID or vector ID.

List asset characters for the authenticated user's fal Assets library.

Create an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.

Update an asset character for the authenticated user's fal Assets library. Prefer vector IDs or request IDs in reference_images for existing fal-generated assets; use fal-hosted image URLs only for standalone images. Unresolved ID references are materialized before character state is added.

Get asset character for the authenticated user's fal Assets library.

Delete asset character for the authenticated user's fal Assets library.

Favorite an asset character for the authenticated user's fal Assets library.

Unfavorite an asset character for the authenticated user's fal Assets library.

List asset tags for the authenticated user's fal Assets library.

Create asset tag for the authenticated user's fal Assets library.

Set tags for an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Update asset tag for the authenticated user's fal Assets library.

Delete asset tag for the authenticated user's fal Assets library.

Upload asset for the authenticated user's fal Assets library.

Get an asset document by vector ID from the authenticated user's fal Assets library. The vector may exist only in Turbopuffer; in that case the response returns the Turbopuffer document with empty local state.

Get the derivation lineage of an asset by asset ID: the inputs it was generated from, the generation requests along the way, and any referenced characters, traversed recursively up to depth levels. Deleted or expired ancestors stay in the graph flagged as tombstones; inputs that were never captured appear as external inputs.

Favorite an asset. Provide a request ID or vector ID; unresolved references are materialized before favorite state is added.

Unfavorite an asset by request ID or vector ID.

List tags for an asset by vector ID. Vectors that have not been saved as assets return an empty tag list.

Assign a tag to an asset. Provide a request ID or vector ID; unresolved references are materialized before tag state is added.

Unassign a tag from an asset by request ID or vector ID.

Returns the Access Control List currently applied to a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users are returned as nicknames where possible.

Authentication: Required. The API key must have the assets:read permission.

Replaces the Access Control List of a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide.

Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent.

Authentication: Required. The API key must have the assets:write permission.

Creates a signed URL that grants temporary access to a fal CDN file, regardless of its ACL. Useful for sharing access-restricted files.

The signature is valid for expiration_seconds (up to 7 days).

Authentication: Required. The API key must have the assets:read permission.

Returns the account-level storage lifecycle settings applied to newly uploaded fal CDN files:

• expiration_duration_seconds: how long files live before being automatically deleted (null disables auto-expiration).

• initial_acl: the default ACL applied to new uploads (null means the system default, which is public).

Both fields are null when the account has never saved settings.

Authentication: Required. The API key must have the account:settings:read permission.

Replaces the account-level storage lifecycle settings applied to newly uploaded fal CDN files. Omitted or null fields are cleared (reset to the system default), so always send the full desired configuration.

ACL rules referencing users that do not exist are dropped. The response reflects the settings actually saved, so verify it contains the rules you sent.

These are the same settings that the per-request X-Fal-Object-Lifecycle-Preference header overrides on individual requests.

Authentication: Required. The API key must have the account:settings:write permission.

Returns billing information for the authenticated account. Use the expand parameter to include additional details.

Expandable Fields:

• credits — Current credit balance and currency

Common Use Cases:

• Monitor available credit balance programmatically

• Display balance in custom dashboards

Returns the list of teams in your organization with their details.

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

Must be called with an admin API key on the organization's root team.

Key Features:

• List all teams within the organization

• Identify the organization's root team via is_org_root

• View team usernames and display names

See fal.ai docs for more details.

Returns paginated usage records across all teams and product lines in your organization, with each record attributed to a specific team via the username field and a product line via the product field.

Covers all three fal product lines:

• model_apis — model API endpoint calls (e.g. fal-ai/flux/dev)

• serverless — fal Serverless SDK billing

• compute — fal Compute (raw instance time)

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

Must be called with an admin API key on the organization's root team.

Key Features:

• Organization-wide usage data across all teams and products

• Filter by team(s) (team_username), product line (product), endpoint, API key (api_key_id), date range, and auth method

• Per-team and per-product attribution on every usage record

• Paginated time series and aggregate summary views

See fal.ai docs for more details.

Exact current catalog lookup with OpenAPI expansion. No generation or inferred model defaults. Schema may be unavailable; inspect actual native fields.

Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.

Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.

Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.

Confirmed paid model request after current native input-schema validation. Exact model_id/input required; image/video commands do not invent fields or choose a default. Queue submissions return receipt only; synchronous timeout may leave an unknown paid outcome. No retry or polling.

One read using the SDK-compatible owner/app root, not the full model subpath. No auto-polling, paid re-submission or arbitrary status URL.

One result read using the receipt/model root. No wait loop, media download, re-submission or auto-upload. Signed credential URLs are redacted; ordinary output media URLs remain account data.

Confirmed native cancellation request. Cancellation receipt is not proof processing stopped or credits were refunded; current provider state controls eligibility. No retry.

Confirmed selected absolute regular non-symlink local file, 1 byte–20 MiB. Uses pinned SDK upload-initiation protocol then a credential-free HTTPS fal.media PUT with redirects refused. No remote URL ingestion, base64 model output, multipart retries or automatic generation.

Local labels/default/auth method only. No keys, token paths, real provider identities or network request.

Local current native method/path/query/header/body schema and exact provenance. No credential or provider request.

Read-only current schema validation and native unit-pricing lookup for all requested async jobs. Hash binds ordered exact inputs/lifecycle/store-IO/profile label/current schemas/unit quotes. Unit pricing is not final cost or a spending cap. No generation, file write or key ownership validation.

Confirmed one-to-ten async jobs. Refetch all current schemas/unit quotes and validate all before first paid submission; refuse changed hash. Submit sequentially, stop on first failure, report known request IDs/failed and unattempted indices. No polling, retries, rollback, continuation or budget guarantee.