Attribution in AI Cost Management

When AI requests run through your AI Gateway, you need to know where they came from. Attribution connects each request to an identity and context.

When attribution is in place, you can use the data in the following ways:

• The cost management Dashboard breaks spend down by user, group, team, or tag so you can see where costs are concentrated.
• The events Explorer lets you filter and compare any of those dimensions over time.
• Budgets can target a specific user, group, or tag value, so you can track spend against a cap at whatever scope matters to your organization.

Attribution works in two tracks as each request passes through the gateway: identity resolution and tag capture.

• Identity resolution: The gateway evaluates the token or credential against the auth strategy attached to the model and resolves a subject. Group and team membership follows from that subject automatically.
• Tag capture: The gateway reads the request headers and records them as tags on the usage event. The gateway captures headers prefixed with ai-cost- without configuration: the part after the prefix becomes the tag key.

The subject is the primary identity attributed to a usage event.

AI Cost Management sets the subject from the following priority chain, using the first value that applies:

1. A valid Kong Identity Principal UUID is on the request.
2. A valid AI Consumer UUID is on the request.
3. The auth strategy type is openid-connect-credential-claim and the token has a sub claim. The sub is the raw value from the token’s sub claim, between 1 and 255 characters with no line break.

When none of these applies, the event has no subject and is unattributed. Unattributed events still appear in totals, and you can still match them by group, tag, and model. In the dashboard and the events view, they show as Unattributed.

Groups and teams record the organizational context of the request’s principal.

Groups and teams don’t come from tag headers. Sending a header such as ai-cost-groups doesn’t populate these fields.

Groups

Groups appear in the event’s groups field as an array of typed references. They come from any of the following sources:

• The request principal’s Kong Identity group memberships (as principal/UUID)
• The request consumer’s gateway consumer groups (as consumer_group/UUID)
• JWT group or groups claims on an openid-connect auth strategy (as oidc/GROUP)

A single event holds at most 64 groups.

Teams

Teams appear in the event’s teams field as an array of principal/UUID references. They come from Kong Identity team membership of the request’s principal only. A single event can hold a maximum of 200 teams.

Tags are key-value pairs attached to a usage event. Tags hold context the caller controls: the project, the ticket, the environment, or any other dimension useful for cost allocation.

The gateway captures tags from request headers. You can set a tag by sending a header named ai-cost- followed by the tag key. For example, to set the project tag to atlas, send the header ai-cost-project: atlas.

Tag and header rules

The ai-cost- headers follow these rules:

• Key: Lowercase ASCII letters, digits, ., _, and -, between 1 and 128 characters.
• Value: Between 1 and 256 characters, no control characters, case-sensitive.
• Header names arrive in lowercase, so ai-cost-Project and ai-cost-project are the same header.
• Each ai-cost- header must appear once per request. The gateway drops the tag when a header is duplicated, even when both values are equal.
• The gateway drops tags with empty values.
• A single event holds at most 64 tags. When a request exceeds this limit, the gateway drops all of its tags.
• Don’t put PII in a tag, for example a name, email, or username. User identity comes from the auth strategy on the model.

Some tools send native headers that the gateway maps to standard tag keys automatically, so you don’t need ai-cost- headers. See Attribution integrations for the supported tools and the tags each one sends.

Standard tag keys

The following standard tag keys define a shared vocabulary for common dimensions. A tag can use any valid key. These conventional names help tags from different tools and teams align.

Custom tag keys

You can define custom keys for any dimension the standard keys don’t cover. A custom key follows the same rules as any other tag key.

To avoid conflicts with future standard keys, prefix custom keys with a namespace, for example acme-cost-center- or internal-team-.

Attribution has two independent parts: the subject on each event and the tags.

Set up subject attribution

Identity attribution comes from the AI Auth Strategy on the AI Model. AI Gateway evaluates the strategy on each request and attributes the request to the authenticated subject, so no further configuration is needed.

Set up header-based attribution

Configure tag capture via headers in the Konnect UI:

1. In Konnect, switch to the AI view.
2. In the sidebar, click Cost Management.
3. In the sidebar, click Attribution.

4. Optional: Click the Header builder tab to help you generate the ai-cost- headers for your tool. Choose the output format (curl, HTTP headers, Claude Code, Codex, OpenCode, or Gemini CLI), enter your tags, and copy the result.

   Note: The Header builder is a helper tool that formats your headers in the correct way. Use the tool to help you build headers, and then copy those headers into your integration. Nothing you enter leaves this page.

5. Click the Integrations tab.
6. Click your integration, or choose Your own code for custom configuration.
7. Follow the on-screen instructions to complete the setup.

After setting up your provider, the AI Gateway captures your configured ai-cost- headers automatically with no additional data plane configuration needed.