> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudidr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```http theme={null}
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

```python theme={null}
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

```python theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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

```bash theme={null}
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

```bash theme={null}
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.

```http theme={null}
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.

```http theme={null}
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.

```http theme={null}
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.

```python theme={null}
# 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](mailto:hello@cloudidr.com) · [llm-ops.cloudidr.com](https://llm-ops.cloudidr.com)*