Cost Attribution

Tag gateway requests with custom labels to track LLM spend by project, team, environment, agent, or any dimension your organization needs. Attribution data flows into the dashboard for visualization and the API for programmatic access.

Adding Tags to Requests

Include the X-CM-Tags header on any gateway request. Tags are comma-separated key=value pairs:


curl https://api.curate-me.ai/v1/openai/chat/completions \
  -H "X-CM-API-Key: cm_sk_xxx" \
  -H "X-Provider-Key: sk-your-key" \
  -H "X-CM-Tags: project=chatbot,team=platform,env=production" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Python


from openai import OpenAI
 
client = OpenAI(
    base_url="https://api.curate-me.ai/v1/openai",
    api_key="sk-your-key",
    default_headers={
        "X-CM-API-Key": "cm_sk_xxx",
        "X-CM-Tags": "project=chatbot,team=platform,env=production",
    },
)

TypeScript


import OpenAI from "openai";
 
const client = new OpenAI({
  baseURL: "https://api.curate-me.ai/v1/openai",
  apiKey: "sk-your-key",
  defaultHeaders: {
    "X-CM-API-Key": "cm_sk_xxx",
    "X-CM-Tags": "project=chatbot,team=platform,env=production",
  },
});

Per-Request Tags

Override default tags on individual requests when you need per-call attribution:


response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "..."}],
    extra_headers={
        "X-CM-Tags": "project=chatbot,feature=onboarding,user_tier=premium",
    },
)

Built-In Attribution Dimensions

The gateway automatically records these dimensions for every request (no tags needed):

Dimension	Source	Example
Model	Request body	`gpt-4o`, `claude-sonnet-4-5`
Provider	Routing	`openai`, `anthropic`, `google`
API Key	`X-CM-API-Key` header	`cm_sk_abc123`
Organization	Key -> org mapping	`org_xyz`

Custom tags via X-CM-Tags add additional dimensions on top of these.

Hierarchical Budgets

The gateway enforces a three-level budget hierarchy. Each level can have its own daily and monthly limits:


Organization ($500/day)
  └── Team: Platform ($200/day)
  │     └── Key: cm_sk_platform_prod ($100/day)
  │     └── Key: cm_sk_platform_staging ($50/day)
  └── Team: ML ($300/day)
        └── Key: cm_sk_ml_prod ($200/day)

When a request arrives, the gateway checks budgets at all three levels. If any level is over budget, the request is blocked with 403.

Configure hierarchical budgets via the dashboard or API:


# Set a team budget
curl -X PUT https://api.curate-me.ai/api/v1/admin/budgets/teams/platform \
  -H "Authorization: Bearer {jwt}" \
  -H "X-Org-ID: org_xyz" \
  -d '{"daily_budget": 200.0, "monthly_budget": 4000.0}'
 
# Set a key budget
curl -X PUT https://api.curate-me.ai/api/v1/admin/budgets/keys/cm_sk_platform_prod \
  -H "Authorization: Bearer {jwt}" \
  -H "X-Org-ID: org_xyz" \
  -d '{"daily_budget": 100.0, "monthly_budget": 2000.0}'

Querying Cost Attribution

By Model


curl "https://api.curate-me.ai/gateway/costs/by-model?days=7" \
  -H "X-CM-API-Key: cm_sk_xxx"


[
  {"dimension": "gpt-4o", "cost": 45.23, "request_count": 1200, "avg_cost": 0.038},
  {"dimension": "gpt-4o-mini", "cost": 3.10, "request_count": 8500, "avg_cost": 0.0004},
  {"dimension": "claude-sonnet-4-5", "cost": 28.50, "request_count": 600, "avg_cost": 0.048}
]

By Provider


curl "https://api.curate-me.ai/gateway/costs/by-provider?days=7" \
  -H "X-CM-API-Key: cm_sk_xxx"

By Custom Tags


curl "https://api.curate-me.ai/gateway/costs/by-tag?tag=project&days=7" \
  -H "X-CM-API-Key: cm_sk_xxx"


[
  {"dimension": "chatbot", "cost": 52.30, "request_count": 5000},
  {"dimension": "search", "cost": 18.40, "request_count": 3200},
  {"dimension": "agents-demo", "cost": 2.10, "request_count": 150}
]

Python SDK


from curate_me import CurateGateway
 
gw = CurateGateway(api_key="cm_sk_xxx")
admin = gw.admin()
 
# Cost by model
costs = admin.get_daily_costs(days=7)
for entry in costs:
    print(f"{entry['model']}: ${entry['cost']:.2f}")

TypeScript SDK


import { CurateMe } from "@curate-me/sdk";
 
const client = new CurateMe({ apiKey: "cm_sk_xxx" });
const costs = await client.costs.getTimeSeries({
  startDate: "2026-03-19",
  endDate: "2026-03-26",
  granularity: "day",
});

Dashboard Views

The cost attribution dashboard shows:

By Model — which models are driving spend
By Provider — cost breakdown across OpenAI, Anthropic, Google, etc.
By Tag — custom attribution dimensions (project, team, env)
By API Key — which keys are consuming the most budget
Time Series — cost trends over time with drill-down

Tag Best Practices

Tag	Purpose	Example
`project`	Which product or feature	`project=chatbot`
`team`	Which team owns the cost	`team=platform`
`env`	Development stage	`env=production`
`agent`	Which agent in a multi-agent system	`agent=triage`
`feature`	Specific feature within a project	`feature=onboarding`
`user_tier`	Customer tier for unit economics	`user_tier=premium`

Keep tag cardinality manageable — avoid per-user or per-request unique values as tag values.

Next Steps

Cost Tracking — budget caps, alerts, and retention
Gateway Cost Tracking — how the recording pipeline works
Dashboard Cost Tracking — cost views in the dashboard
Governance Chain — budget enforcement steps (2, 2.5, 3)