Falai/organization
fal.ai Organization — teams, usage, billing events, focus reports
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.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | 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. |
| Argument | Type | Description |
|---|---|---|
| limit? | number | 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. |
| 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. |
| endpoint_id? | union | 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 |
| request_id? | union | Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2 |
| api_key_id? | union | Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2 |
| team_username? | union | Filter billing events by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns billing events across all teams. |
| expand? | union | Data to include in the response. Use 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). |
| Argument | Type | Description |
|---|---|---|
| limit? | number | 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. |
| 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. |
| timezone? | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. |
| timeframe? | enum | 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 | 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 | 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 |
| api_key_id? | union | Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2 |
| team_username? | union | Filter by one or more team usernames within the organization. Accepts a comma-separated list or repeated parameter. If not provided, returns usage across all teams. |
| product? | union | Restrict results to one or more product lines. Accepts a comma-separated list or repeated parameter. Defaults to all three (model_apis, serverless, compute). |
| expand? | union | Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' for a resolved authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required. |
Resources
2026.10.14.1
Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.
Upgrade note: Metadata only. No code, schema, or behavioral changes.
2026.10.07.1
Fixed: A stalled fal.ai request no longer hangs the method. Every request now has a 60-second deadline that covers the response body, and a timeout raises an error naming the HTTP method and URL.
Fixed: An empty 2xx response body (such as a 202 or 204) is handled
explicitly. Paginated list calls treat it as an empty page instead of failing
with a bare SyntaxError. Methods that must return data (get, create, update,
and unpaginated list) raise an error naming the HTTP method and path instead of
failing later with a TypeError. Delete and action methods still accept an
empty body. A malformed JSON body now raises an error that names the HTTP
method, path, and status code.
Changed: A Retry-After header on a 429 response is capped at 30 seconds
per retry, so a large value can no longer stall a call for minutes. Retry count
is unchanged.
No methods, arguments, or resource schemas changed. Apart from the hardening above, behavior is the same as the previous version.
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.2
Add quantity/unit fields to billing event schema; output_units/custom_units are now documented as deprecated aliases of quantity/unit (still returned, no removal). Also: quantity/unit and the new usage fields (percent_discount/cost_subtotal/cost_discount/cost_total) are generated as optional/nullable-optional so reading a resource stored under an older model version no longer throws Required now that the live API adds these fields.
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.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.
- 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