Skip to main content
Request tags let you attach your own key=value labels to a request. fal stores the tags with the request, and reports usage and estimated cost against them. Use tags to attribute spend to your own dimensions, such as a team, an environment, or a feature. Tags do not change how fal runs a request. They do not change the price, and the model does not receive them.
Availability: Tag reporting must be enabled for your account. Contact your account team or support@fal.ai to request access. Until fal enables it, you can send tags, but no report shows them.

​
Send Tags

Send the X-Fal-Tags header on the request. Pack every tag into one header value and separate the tags with commas.
The header is the same for a queue submit, a synchronous run, and an HTTP stream.

​
Format and Limits

fal splits each tag on the first = character, so a value can contain more = characters. fal also removes the spaces around a key and a value. If you send the same key two times, the last value wins. The limits count every tag you send, before fal removes the duplicate keys.

​
Reserved Keys and Values

Keys that start with fal. are reserved for fal. The gateway drops a reserved key from your input. The value * and any value that starts with ( and ends with ), such as (untagged), are also reserved for fal. The gateway drops a tag that has one of these values. A value with parentheses inside it, such as Acme (EU), is valid.

​
Invalid Tags

The gateway never fails a request because of a tag. It drops each tag that breaks a rule, and it keeps the rest. The gateway still runs a request that has no valid tag. When the gateway drops any tag content, the response carries X-Fal-Tags-Dropped: 1. The header does not report which tag the gateway dropped or why. Check for this header while you introduce tagging. The client subscribe() method does not return the response headers. To read the header, send the request with curl -i or with your own HTTP client.

​
Activation

fal reports on activated tags only, and only for an account that has tag reporting enabled. fal can activate a tag key in two ways.
  • Value-level activation. fal activates each key=value pair that you name. Your reports show only the activated values of the key. This is the default.
  • Key-level activation. fal activates the key for all of its values. You can filter your reports by any value that you send under the key.
fal enables reporting and activates the tags for you. When you request access, tell your account team or fal support which tag keys and values to report on. For key-level activation, give the key and ask for all values. fal keeps the tags you send before activation. Those tags appear in your reports after fal activates them, so you do not lose the history. Keep to a small, stable set of keys, such as env, team, and feature. Each account has a cap on the number of activated keys, and a cap on the number of values per key. A key-level activation counts toward the key cap. The cap on values per key does not apply to it.

​
Key-Level Activation

Use key-level activation for a key that has too many values to name one by one. An example is a customer_id key that holds a token for each of your customers. Your reports do not group by a key-level key, because each value would split the report into too many rows. The reports show the key in these ways.
  • Usage & Billing page. The card for the key shows the number of distinct values. It also shows the cost or requests with and without the key. The page does not list the values.
  • Filter by an exact value. To see the usage of one value, type the full value in the Tag filter on the Usage & Billing page. The filter does not suggest values.
  • FOCUS export. The Tags column does not include a key-level key. The cost of the tagged requests stays in the export.
Read these caveats before you ask for key-level activation.
  • fal does not check the values. A person who can see your reports can filter by any value of the key. Use key-level activation only for a key whose values are all safe to report.
  • The activation is retroactive. You can also filter by the values that you sent before the activation. You cannot exclude one value from a key-level activation.

​
Where Tags Appear

After fal activates your tags, the tags appear in these places.
  • Usage. Group and filter your usage by an activated tag on the Usage & Billing page in the dashboard. You can filter by a key-level key, but you cannot group by it.
  • FOCUS export. The FOCUS cost and usage report can fill its Tags column from your activated tags. Call the FOCUS endpoint with source=tagged-estimate. An organization root uses the same source on the organization FOCUS endpoint.
  • Billing events. Call the billing events endpoint with source=tagged-billed. Each event has a tags object, and you can filter the events with tag=key=value.
The other FOCUS sources, invoice and estimate, leave the Tags column empty. The FOCUS report is an enterprise feature, so ask fal support to enable it for your account. Recent usage shows up later in a tagged source than in its default source. For example, tagged-estimate is delayed relative to estimate, and tagged-billed is delayed relative to billed. The Usage & Billing page and the FOCUS export report estimated cost, not invoiced cost.

​
Coverage

Tag reporting covers authenticated, per-request-billed calls to fal Model APIs. That is the traffic that produces a per-request cost. These paths do not report tagged cost.
  • Realtime and WebSocket connections. fal does not capture tags on a WebSocket connection.
  • Your own deployed apps. fal captures the tags on the request. Per-request cost attribution for a deployed app is not available yet.

​
Keep Tags Safe to Report

Never put personal data or a secret in a tag. Your usage reports and your FOCUS export show the tag values. Replace a sensitive identifier with a token, and send the token as the tag value. fal keeps a request’s tags for as long as it keeps the billing record for that request.

Platform Headers

Every platform header you can set on a request, in one place