Skip to main content
The AI Gateway uses HTTP headers to control authentication, request routing, retries, and metadata tagging. This page covers custom metadata and the available request and response headers.

Custom Metadata

You can tag requests with custom metadata using the X-TFY-METADATA header. Metadata is a JSON object where both keys and values must be strings, with a maximum value length of 128 characters.

Sending Metadata

Automatic Metadata Injection

In addition to sending metadata explicitly via the X-TFY-METADATA header, TrueFoundry can automatically inject metadata into requests based on your access configuration. This ensures consistent tagging without requiring changes to client code.
When you assign tags to a virtual account, those tags are automatically added as metadata to every request authenticated with that account’s token. This lets you tag all traffic from a specific application or service without modifying any client code.For example, if a virtual account has tags {"application": "booking-bot", "environment": "prod"}, every request made with that account’s token will carry those metadata keys — enabling filtering, cost attribution, and routing based on those values.
When a Personal Access Token (PAT) is associated with a team, and that team has tags configured, those team tags are automatically injected as metadata into every request made with that PAT. This provides automatic team-level attribution for all API usage.For example, if a PAT is linked to the “ML Platform” team which has tags {"cost_center": "eng-ml", "department": "engineering"}, every request through that PAT will include those metadata keys. Admins can mandate team selection for PATs to ensure every PAT is associated with a team.
Combine automatic metadata injection with the Metadata Validation guardrail to enforce that every request carries the metadata your organization requires — whether injected automatically or sent by the client.

Use Cases

Tag every request with attributes like application, environment, or customer_id and slice your observability data by them.Filter LogsFilter your request logs using one or more metadata keys to isolate specific requests. This is useful for debugging or analyzing usage patterns for a particular feature, environment, or user.
TrueFoundry dashboard showing how to filter requests using custom metadata keys

Filtering requests using custom Metadata Keys

Create Custom MetricsGroup metrics by metadata keys to create custom visualizations. For example, monitor cost and usage per customer by grouping with a customer_id key.
Dashboard view showing metrics grouped by customer_id metadata key with usage statistics per customer

Grouping metrics by a custom 'customer_id' metadata key

Use metadata in the when block of gateway configurations to target specific applications, environments, or customers — without changing client code. For example, to rate limit requests from the dev environment:
You can also use metadata to configure Load Balancing and Fallbacks. Learn more in Virtual Models and Routing Config.

Request Headers

Response Headers

Server-Timing Breakdown

When inspecting network requests in your browser’s developer tools, the server-timing header provides a detailed performance breakdown: Metrics like load balancing (0 ms), rate limiting (0 ms), and cost budget (0 ms) show zero duration because these configs weren’t triggered for this particular request.
Server-timing header in browser developer tools showing request processing breakdown

Server-timing header in browser developer tools