Metadata
Attach consistent project, feature, environment and ownership metadata to make AI spend traceable and governable.
Metadata turns raw AI usage into useful FinOps data.
Without metadata, Kadryn can still record requests, but it cannot reliably answer who owns the spend, which product feature caused it, which environment generated it or which policy should apply.
Minimum metadata
Send at least:
| Metadata | Why it matters |
|---|---|
project | Connects usage to a product or service. |
feature | Shows which feature, workflow or agent produced the cost. |
environment | Separates prod, staging, dev, test and preview traffic. |
Recommended metadata model
| Metadata | Gateway header | Direct ingest field |
|---|---|---|
| Project | X-Kadryn-Project | project |
| Team | X-Kadryn-Team | team |
| Feature | X-Kadryn-Feature | feature |
| Environment | X-Kadryn-Environment | environment |
| Cost center | X-Kadryn-Cost-Center | costCenter |
| Budget owner | X-Kadryn-Budget-Owner | budgetOwner |
| Customer | X-Kadryn-Customer | customer |
| Tenant | X-Kadryn-Tenant | tenant |
| Workflow | X-Kadryn-Workflow | workflow |
| Agent | X-Kadryn-Agent | agent |
| Request group | X-Kadryn-Request-Group-Id | requestGroupId |
Gateway example
curl "$KADRYN_GATEWAY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $KADRYN_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Kadryn-Project: billing-api" \
-H "X-Kadryn-Team: platform" \
-H "X-Kadryn-Feature: invoice-assistant" \
-H "X-Kadryn-Environment: prod" \
-H "X-Kadryn-Cost-Center: finance-ops" \
-H "X-Kadryn-Workflow: invoice-run" \
-d '{
"model": "gpt-4.1-mini",
"messages": [
{
"role": "user",
"content": "Summarize invoice status."
}
]
}'
Direct ingest example
{
"timestamp": "2026-07-06T12:00:00.000Z",
"provider": "openai",
"model": "gpt-4.1-mini",
"inputTokens": 1200,
"outputTokens": 300,
"costCents": "4",
"project": "billing-api",
"team": "platform",
"feature": "invoice-assistant",
"environment": "prod",
"costCenter": "finance-ops",
"workflow": "invoice-run"
}
Naming rules
Use stable, readable values.
Good:
billing-api
support-agent
prod
platform
invoice-run
Avoid:
misc
unknown
temp
random-uuid-per-request
user-entered-free-text
Metadata should be stable enough for dashboards, policies and allocation.
Environments
Recommended environment values:
prod;staging;dev;test;preview;local.
Keep production traffic separate from development and synthetic traffic.
Customer and tenant metadata
Use customer or tenant metadata when you need unit economics.
Examples:
- cost per customer;
- cost per tenant;
- cost per workflow;
- cost per agent;
- margin analysis;
- customer-level cost anomalies.
Do not send sensitive customer data as metadata. Use stable internal IDs or safe labels.
Metadata and Guardrails
Policies and caps can depend on metadata.
Examples:
- block production requests without
project; - cap spend for a project;
- require approval for a model in
prod; - allow test traffic only in
dev; - route customer-facing agents differently.
Poor metadata creates weak policies.
Metadata and allocation
Cost allocation uses metadata to connect spend to:
- teams;
- projects;
- features;
- cost centers;
- budget owners;
- customers;
- workflows.
If spend is unallocated, check whether metadata is missing, inconsistent or not mapped to allocation rules.
Troubleshooting
Costs are unallocated
Check project, team, cost center and budget owner metadata.
Policies do not apply
Check exact metadata values. A policy for prod will not match production unless your workspace normalizes it.
Feature reporting is noisy
Use a stable feature taxonomy. Avoid generating a new feature value for every request.