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.
A tags option is on the way in the fal clients. It takes a key=value mapping, checks it against the limits below, and packs it into this one header. Until that option ships, set the header yourself.

​
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

Keys that start with fal. are reserved for fal. The gateway drops a reserved key from your input.

​
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 response does not carry the header when the gateway keeps every tag. The header reports only that a drop happened. It does not report which tag, and it does not report the reason. Check for this header while you introduce tagging. It is the signal that your tags break one of the rules above. 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 key=value pairs only, and only for an account that has tag reporting enabled. fal does both steps for you. When you request access, tell your account team or fal support which tag keys and values to report on. 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.

​
Where Tags Appear

After fal activates your tags, the tags appear in two places.
  • Usage. Group and filter your usage by an activated tag on the Usage & Billing page in the dashboard.
  • 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.
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. Tag breakdowns update about every 15 minutes. In this phase both surfaces 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 in this phase.
  • 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