Cost Attribution (Tagging)

Tagging is how Cloudidr LLM Ops cost attributes every API request to the right part of your organization. Three optional HTTP headers added to your request unlock full cost visibility by department, project, and agent — across every model and provider.

How Tagging Works

Tags are passed as standard HTTP headers on each request through the Cloudidr proxy, alongside your X-Cloudidr-Key authentication header. Cloudidr logs each tag value alongside the request’s token count, cost, model, and timestamp. The result is a fully attributed cost record — queryable by any tag dimension in your LLM Ops dashboard.

X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Department:   Engineering
X-Project:      Customer-Search
X-Agent:        Query-Optimizer

The Three Tag Dimensions

Header	Purpose	Example values
`X-Department`	Business unit, org division, or team	`Engineering`, `Marketing`, `Sales`, `Data-Science`
`X-Project`	Specific initiative, workload, or product area	`Customer-Search`, `Seo-Pipeline`, `Lead-Gen-v2`
`X-Agent`	Individual agent, service, or use case name	`Monitoring`, `SEO`, `Lead Gen`, `API Service`

X-Department can represent a department or a team — whichever fits your org structure. Some organizations tag by formal department (Engineering, Marketing). Others use it as a team label (Backend, DevOps, Content). Both are valid. If you only have one level of group hierarchy, use X-Department for it.

Flexibility — Use What You Need

All three tags are completely optional. Use none, one, two, or all three — any combination works.

Tags used	What you get in the dashboard
None	Organization-wide token and cost totals only
`X-Agent` only	Per-agent cost and savings breakdown
`X-Department` only	Cost rollup by business unit or team
`X-Department` + `X-Agent`	Department-level rollup with per-agent drill-down
`X-Project` + `X-Agent`	Project-level cost with per-agent attribution
All three	Full cost attribution: department → project → agent

Start with just X-Agent and add more dimensions as your observability needs grow.

Code Examples

Python — Anthropic

from anthropic import Anthropic

client = Anthropic(
    api_key="your-anthropic-key",
    base_url="https://api.llm-ops.cloudidr.com/v1",
    default_headers={
        "X-Cloudidr-Key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "X-Department": "Engineering",    # Optional: Organize by department/team
        "X-Project": "Customer-Search",   # Optional: Organize by project
        "X-Agent": "Query-Optimizer"      # Optional: Organize by agent/use case
    }
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this support ticket."}]
)

Python — OpenAI

from openai import OpenAI

client = OpenAI(
    api_key="your-openai-key",
    base_url="https://api.llm-ops.cloudidr.com/v1",
    default_headers={
        "X-Cloudidr-Key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "X-Department": "Marketing",       # Optional: Organize by department/team
        "X-Project": "SEO-Pipeline",       # Optional: Organize by project
        "X-Agent": "SEO"                   # Optional: Organize by agent/use case
    }
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Write SEO meta descriptions."}]
)

JavaScript / Node.js — Anthropic

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: 'your-anthropic-key',
  baseURL: 'https://api.llm-ops.cloudidr.com/v1',
  defaultHeaders: {
    'X-Cloudidr-Key': 'trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'X-Department': 'Sales',              // Optional: Organize by department/team
    'X-Project': 'Lead-Qualification',    // Optional: Organize by project
    'X-Agent': 'Lead Gen'                 // Optional: Organize by agent/use case
  }
})

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Qualify this inbound lead.' }]
})

JavaScript / Node.js — OpenAI

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'your-openai-key',
  baseURL: 'https://api.llm-ops.cloudidr.com/v1',
  defaultHeaders: {
    'X-Cloudidr-Key': 'trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'X-Department': 'Engineering',        // Optional: Organize by department/team
    'X-Project': 'Infra-Monitoring',      // Optional: Organize by project
    'X-Agent': 'Monitoring'               // Optional: Organize by agent/use case
  }
})

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Check system health status.' }]
})

cURL — Anthropic

curl https://api.llm-ops.cloudidr.com/v1/messages \
  -H "Authorization: Bearer your-anthropic-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Department: Engineering" \
  -H "X-Project: Infra-Monitoring" \
  -H "X-Agent: Monitoring" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Check system health status."}]
  }'

cURL — OpenAI

curl https://api.llm-ops.cloudidr.com/v1/chat/completions \
  -H "Authorization: Bearer your-openai-key" \
  -H "Content-Type: application/json" \
  -H "X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Department: Marketing" \
  -H "X-Project: PPC-Campaigns" \
  -H "X-Agent: PPC Campaigns" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Generate ad copy."}]
  }'

Real-World Tagging Patterns

Pattern 1 — Agent Only

Suitable for single-team setups or early-stage cost tracking. Immediately surfaces per-agent cost breakdown in Agent Explorer.

X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Agent: Chatbot

Dashboard result: Total cost and tokens broken down per agent. Budget Guard limits can be set immediately.

Pattern 2 — Department as Team Label

Use X-Department to represent a team when your org doesn’t distinguish department from team hierarchy.

X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Department: Backend
X-Agent: API Service

Dashboard result: Team-level cost rollup (Backend) with per-agent detail (API Service).

Pattern 3 — Full Attribution (Recommended for Scale)

Full three-tag setup gives the complete org cost picture — department → project → agent — in a single dashboard view.

X-Cloudidr-Key: trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Department: Marketing
X-Project: SEO-Pipeline
X-Agent: SEO

Dashboard result:

Department: Marketing → $900/month
Project: SEO-Pipeline → $900/month
Agent: SEO → $900/month, 91.2% savings rate

Pattern 4 — Multi-Agent Project

Tag each agent call with the same project so the dashboard rolls them up into a single project cost view.

# Agent 1 — research step
headers_research = {
    "X-Cloudidr-Key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "X-Department": "Sales",
    "X-Project": "Outbound-Pipeline",
    "X-Agent": "Lead Research",
}

# Agent 2 — drafting step
headers_draft = {
    "X-Cloudidr-Key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "X-Department": "Sales",
    "X-Project": "Outbound-Pipeline",
    "X-Agent": "Email Drafter",
}

# Agent 3 — qualification step
headers_qualify = {
    "X-Cloudidr-Key": "trk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "X-Department": "Sales",
    "X-Project": "Outbound-Pipeline",
    "X-Agent": "Lead Qualifier",
}

Dashboard result: Outbound-Pipeline total cost shown in one view, split across Lead Research, Email Drafter, and Lead Qualifier.

What You See in the Dashboard

Once tags are flowing, the LLM Ops dashboard lets you:

Slice by any tag dimension — filter spend by X-Department, X-Project, or X-Agent
Compare across departments/teams — see which group drives the most spend and at what savings rate
Set Budget Guard limits per agent — Budget Guard uses the X-Agent value to enforce per-agent monthly budgets
Track project-level ROI — tie token spend directly to a business initiative using X-Project
Identify runaway agents — an agent with unexpectedly high token consumption shows up immediately in Agent Explorer

Tag Naming Conventions

⚠️ Tag values are case-sensitive and matched by exact string. Engineering and engineering are stored as two separate groups in the dashboard. A single inconsistency across your codebase will split what should be one group into two. Establish your convention once and enforce it everywhere.

Recommended: use Title Case for all tag values.

X-Department → Engineering, Marketing, Inside Sales, Data Science
X-Agent → Lead Gen, Monitoring, SEO, API Service, Content Writer
X-Project → Customer-Search, SEO-Pipeline, Lead-Gen-V2 (hyphenated Title Case works well for programmatic names)

Title Case reads cleanly as display labels in the dashboard, matches how agents appear in Agent Explorer, and reduces the most common mistake — one service using marketing and another using Marketing creating two separate cost groups. Other conventions to follow:

Use hyphens for multi-word project names — Customer-Search not Customer Search (spaces can cause issues in some header parsers)
Keep values short and stable — these become filter labels and budget group identifiers; changing them mid-deployment splits your historical data
Never mix conventions — if you start with Engineering, don’t switch to engineering or ENGINEERING mid-project

Summary

Header	Required	Description	Example
`X-Cloudidr-Key`	Yes	Your Cloudidr tracking key	`trk_xxxx...`
`X-Department`	No	Department or team	`Engineering`
`X-Project`	No	Project or workload	`Customer-Search`
`X-Agent`	No	Agent or service name	`Lead Gen`

Use none, one, or all three optional tags — tagging is additive. Every tag unlocks a new dimension of cost visibility in your LLM Ops dashboard without any other configuration required.

For questions or integration help → support@cloudidr.com · llm-ops.cloudidr.com

Get Started

LLM Ops

Flex Compute

How Tagging Works

The Three Tag Dimensions

Flexibility — Use What You Need

Code Examples

Python — Anthropic

Python — OpenAI

JavaScript / Node.js — Anthropic

JavaScript / Node.js — OpenAI

cURL — Anthropic

cURL — OpenAI

Real-World Tagging Patterns

Pattern 1 — Agent Only

Pattern 2 — Department as Team Label

Pattern 3 — Full Attribution (Recommended for Scale)

Pattern 4 — Multi-Agent Project

What You See in the Dashboard

Tag Naming Conventions

Summary

​How Tagging Works

​The Three Tag Dimensions

​Flexibility — Use What You Need

​Code Examples

​Python — Anthropic

​Python — OpenAI

​JavaScript / Node.js — Anthropic

​JavaScript / Node.js — OpenAI

​cURL — Anthropic

​cURL — OpenAI

​Real-World Tagging Patterns

​Pattern 1 — Agent Only

​Pattern 2 — Department as Team Label

​Pattern 3 — Full Attribution (Recommended for Scale)

​Pattern 4 — Multi-Agent Project

​What You See in the Dashboard

​Tag Naming Conventions

​Summary

How Tagging Works

The Three Tag Dimensions

Flexibility — Use What You Need

Code Examples

Python — Anthropic

Python — OpenAI

JavaScript / Node.js — Anthropic

JavaScript / Node.js — OpenAI

cURL — Anthropic

cURL — OpenAI

Real-World Tagging Patterns

Pattern 1 — Agent Only

Pattern 2 — Department as Team Label

Pattern 3 — Full Attribution (Recommended for Scale)

Pattern 4 — Multi-Agent Project

What You See in the Dashboard

Tag Naming Conventions

Summary