Falai/serverless

@webframp/falai/serverlessv2026.10.21.1· Apache-2.0· 5d agoBEHAVIORS

01README

fal.ai Serverless — app deployments, queue, revisions, files, logs, metrics, requests, usage

02Release Notes

2026.10.21.1

Changed: The README, the apiToken description and the missing-key error now direct you to store the fal.ai API key in a vault (swamp vault put falai API_KEY) and wire it with --global-arg 'apiToken=${{ vault.get("falai", "API_KEY") }}'. The README previously showed --global-arg apiToken=FAL_API_KEY, which invited passing the key as a literal. The FAL_KEY environment variable is still read as a fallback, but it is not redacted and is not recommended.

No method behavior changed. Stored resources need no migration.

03Behaviors1

@webframp/falai/serverlessv2026.10.21.1falai/serverless.ts

Global Arguments

Argument	Type	Required	Description
apiToken?	string	no	fal.ai API key. Wire it with ${{ vault.get("falai", "API_KEY") }}; never pass the literal value. The FAL_KEY environment variable is read as a fallback, but it is not redacted and is not recommended.

fn get_analytics(limit?: number, cursor?: string, start?: union, end?: union, timezone?: string, timeframe?: enum, bound_to_timeframe?: enum, endpoint_id?: union, expand?: union)

Analytics

Argument	Type	Required	Description
limit?	number	no	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
cursor?	string	no	Pagination cursor from previous response. Encodes the page number.
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
timezone?	string	no	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
timeframe?	enum	no	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?	enum	no	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	no	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
expand?	union	no	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.

fn list_apps(environment?: string, search?: string, expand?: union)

List Applications

Argument	Type	Required	Description
environment?	string	no	Environment to list apps from. Defaults to the main environment.
search?	string	no	Case-insensitive substring match on the app name
expand?	union	no	Fields to expand in the response. Use endpoints to include each app's registered route-level endpoint ids.

fn get_app_queue_info(owner: string, name: string)

Queue Size

Argument	Type	Required	Description
owner	string	yes	Username of the app owner
name	string	yes	Application name

fn delete_serverless_flush_app_queue(owner: string, name: string)

Flush Application Queue

Argument	Type	Required	Description
owner	string	yes	Username of the app owner
name	string	yes	Application name

fn get_runner_history(owner: string, name: string, start?: union, end?: union, timeframe?: enum, aggregation?: enum)

Runner State History

Argument	Type	Required	Description
owner	string	yes	Username of the app owner
name	string	yes	Application name
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
timeframe?	enum	no	Bucket size for the time series (auto-detected from the date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d).
aggregation?	enum	no	How runner counts are aggregated within each bucket: 'max' shows peak concurrency (capacity analysis), 'avg' shows mean concurrency (utilization analysis).

fn list_app_events(owner: string, name: string, start?: union, end?: union, category?: union, limit?: number, cursor?: string)

Application Events

Argument	Type	Required	Description
owner	string	yes	Username of the app owner
name	string	yes	Application name
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
category?	union	no	Filter by event category. Repeat the parameter to include multiple categories: ?category=deployment_started&category=config_changed
limit?	number	no	Maximum number of events to return per page (1-1000)
cursor?	string	no	Pagination cursor from previous response

fn list_app_revisions(owner: string, name: string, limit?: number, cursor?: string)

Application Revisions

Argument	Type	Required	Description
owner	string	yes	Username of the app owner
name	string	yes	Application name
limit?	number	no	Maximum number of revisions to return per page (1-100)
cursor?	string	no	Pagination cursor from previous response

fn list_root()

List files (root)

fn list_directory(dir: string)

List files (directory)

Argument	Type	Required	Description
dir	string	yes	Directory path to list

fn upload_from_url(file: string, url: string)

Upload file from URL

Argument	Type	Required	Description
file	string	yes	Target file path (including filename)
url	string	yes	Publicly accessible URL for the file

fn serverless_logs_history(limit?: number, cursor?: string, start?: union, end?: union, app_id?: union, revision?: string, run_source?: enum, traceback?: boolean, search?: string, level?: string, job_id?: string, request_id?: string, items: array)

Logs history (paginated)

Argument	Type	Required	Description
limit?	number	no	Number of results per page
cursor?	string	no	Pagination cursor from previous response (timestamp-based). Use as 'until' parameter for next page.
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
app_id?	union	no	Filter by specific app ID(s) in '<owner>/<name>' format (e.g. 'fal-ai/my-app'). Accepts 1-50 app IDs. Supports comma-separated values: ?app_id=fal-ai/foo,fal-ai/bar or array syntax: ?app_id=fal-ai/foo&app_id=fal-ai/bar
revision?	string	no	Filter by revision
run_source?	enum	no	Filter by run source
traceback?	boolean	no	Include tracebacks
search?	string	no	Free-text search
level?	string	no	Minimum log level
job_id?	string	no	Filter by job id
request_id?	string	no	Filter by request id
items	array	yes

fn list_requests_by_endpoint(limit?: number, cursor?: string, endpoint_id?: union, start?: union, end?: union, status?: enum, request_id?: string, expand?: union, sort_by?: enum)

List requests by endpoint(s)

Argument	Type	Required	Description
limit?	number	no	Number of items to return per page (max 100)
cursor?	string	no	Pagination cursor encoding the page number
endpoint_id?	union	no	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
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
status?	enum	no	Filter by request status
request_id?	string	no	Filter by specific request ID
expand?	union	no	Fields to expand in the response. Use payloads to include input and output payloads. Use billing to include billable_units per request; billing also requires the `billing:usage:read` permission.
sort_by?	enum	no	Sort results by end time or duration

fn get_usage(limit?: number, cursor?: string, start?: union, end?: union, timezone?: string, timeframe?: enum, bound_to_timeframe?: enum, app?: union, search?: string, expand?: union)

Usage

Argument	Type	Required	Description
limit?	number	no	Maximum number of items to return. Actual maximum depends on query type and expansion parameters.
cursor?	string	no	Pagination cursor from previous response. Encodes the page number.
start?	union	no	Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.
end?	union	no	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.
timezone?	string	no	Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed.
timeframe?	enum	no	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?	enum	no	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.
app?	union	no	Filter to one or more serverless apps, matched exactly against the `app` value in the response (deployed name, owner prefix stripped). Accepts a comma-separated list or repeated parameter (1-50). For partial/name-only matching use `search`.
search?	string	no	Case-insensitive substring match on the app name — returns every app whose name contains this term (e.g. `search=autohdr` matches all `autohdr-*` apps across environments). Combined with `app` via AND when both are given.
expand?	union	no	Data to include in the response. Use 'time_series' for time-bucketed data and 'summary' for aggregate statistics across the entire window. At least one is required.

Resources

get_analytics(infinite)— Analytics

apps(infinite)— List Applications

app_queue_info(infinite)— Queue Size

get_runner_history(infinite)— Runner State History

app_events(infinite)— Application Events

app_revisions(infinite)— Application Revisions

list_root(infinite)— List files (root)

list_directory(infinite)— List files (directory)

upload_from_url(infinite)— Upload file from URL

serverless_logs_history(infinite)— Logs history (paginated)

requests_by_endpoint(infinite)— List requests by endpoint(s)

get_usage(infinite)— Usage

04Previous Versions6

2026.10.14.2Apache-2.0Oct 14, 2026

2026.10.14.2

Fixed: upload_from_url now writes one resource per file path instead of overwriting a single upload_from_url-current instance.

Upgrade note: No methods or arguments changed. Data previously stored under upload_from_url-current is not moved; re-run the action to write the new instance.

2026.10.14.1Apache-2.0(was none)Oct 14, 2026

2026.10.14.1

Fixed: Methods that write a singleton resource failed on current swamp with Data name 'latest' is reserved for internal use.

Changed: Singleton get and action methods now write their data under list_root-current, serverless_logs_history-current, upload_from_url-current instead of latest. Anything that read data.latest("<model>", "latest") or queried name == "latest" must use the new name.

Upgrade note: Data previously stored under latest is not migrated; re-run the method to populate the new name. No attribute schemas changed.

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

2026.09.18.1Sep 20, 2026

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.2Sep 17, 2026

2026.09.17.2

Add net_unit_price field to the billing/usage schema, generated as optional so reading a resource stored under an older model version no longer throws Required now that the live API adds this field.

2026.09.15.1Sep 15, 2026

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.09.10.4

Fixed:

Resource instance names for get/update methods with two or more path parameters (e.g. get_app_queue_info(owner, name), get_workflow(username, workflow_name)) were built by joining raw values with "_". Two distinct owner/name pairs that split differently around an underscore (e.g. "john"/"doe_app" and "john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.

Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.

2026.09.10.4Sep 10, 2026

2026.09.10.4

Fixed:

Resource instance names for get/update methods with two or more path parameters (e.g. get_app_queue_info(owner, name), get_workflow(username, workflow_name)) were built by joining raw values with "_". Two distinct owner/name pairs that split differently around an underscore (e.g. "john"/"doe_app" and "john_doe"/"app") produced the identical instance name and collided. Multi-param instance names are now derived from a hash of the JSON-encoded parameter tuple, which delimits each part unambiguously.

Upgrade note: No schema changes. All fixes are internal to method execution; existing stored resources are unaffected.

05Stats

100 / 100

Downloads

Archive size

24.7 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License2/2earned
Verified public repository2/2earned

Repository

https://github.com/webframp/swamp-extensions

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

07Labels

#falai #serverless #apps #deployment