How do I attribute LLM costs by feature and team?

Pass X-Cost-Feature and X-Cost-Department headers on your Cognocient proxy calls. Every attributed call appears in your dashboard broken down by feature and team — no code changes beyond adding the headers.

Start here — 2 headers unlock 80% of the value

You don't need to add every header on day one. These two are all you need to unlock the most useful dashboards:

Add them now, see results immediately.

client = OpenAI(
    api_key="sk-cog-YOUR-PROXY-KEY",
    base_url="https://api.cognocient.com/v1",
    default_headers={
        "X-Cost-Feature":    "ticket-resolver",
        "X-Cost-Department": "customer-success",
    }
)
# Every call from this client is now tagged — no extra_headers needed

What you'll see after tagging

Within seconds of your first tagged call, the dashboard updates:

The Spend by Feature and Spend by Department charts light up automatically. No configuration required.

Naming conventions

Use lowercase hyphen-separated names. Cognocient aggregates by exact string match.

Good:   ticket-resolver    customer-success    pdf-extractor
Bad:    Ticket Resolver    CustomerSuccess     PDF_EXTRACTOR

If you have multiple services, tag each one at the client level with its own feature name. This gives you automatic per-service cost breakdown with zero per-call overhead.

Add more context when you're ready

The next two headers that deliver the most value:

Track individual users — X-Cost-User

Pass an internal user ID (never raw email or PII). Unlocks the Users tab showing your most expensive users and cost-per-user trends.

extra_headers={
    "X-Cost-Feature":    "ticket-resolver",
    "X-Cost-Department": "customer-success",
    "X-Cost-User":       f"user_{user_id}",    # internal ID, not email
}

Track conversations — X-Cost-Session

Pass a unique ID for each conversation or task. Unlocks the Sessions tab showing total cost per conversation, turn count, and context growth.

import uuid
 
session_id = f"sess-{uuid.uuid4()}"   # generate once when the conversation starts
 
def chat(messages: list, user_id: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        extra_headers={
            "X-Cost-Feature": "support-chat",
            "X-Cost-Session": session_id,      # same ID for all turns in this conversation
            "X-Cost-User":    f"user_{user_id}",
        }
    )

What attribution headers does Cognocient support?

All headers are optional. Use what's relevant to your product.

GL account tagging — for finance teams

Add X-Cost-GL-Account to route AI spend to specific cost centres in your accounting system. The value appears as-is in the FOCUS 1.1 export, so your accounting team can reconcile without any mapping.

extra_headers={
    "X-Cost-Feature":    "pdf-extractor",
    "X-Cost-Department": "data-team",
    "X-Cost-GL-Account": "5100-software",   # appears in FOCUS export
}

Workstream attribution — tie spend to JIRA tickets and PRs

Use X-Cost-Session with your ticket or PR ID to see exactly how much AI spend each story or PR generated.

# Tag calls with a JIRA ticket
extra_headers={"X-Cost-Session": f"JIRA-{story_id}"}
 
# Tag calls with a GitHub PR
extra_headers={"X-Cost-Session": f"pr-{pr_number}"}

The Workstreams dashboard shows each session with total cost, call count, duration, and models used:

This answers the question your engineering manager and CFO both ask: "What work did we spend that AI budget on?"

Per-run attribution — for agent workflows

For autonomous agents that run multiple steps, pass a unique X-Cost-Run-ID for the entire execution. Cognocient tracks total spend per run. When a run exceeds its per-run budget, only that run is blocked — other concurrent runs continue normally.

When multiple subagents run concurrently within the same orchestrated task — for example, up to 16 concurrent subagents in a single Dynamic Workflows-style run — per-call budget checks alone can't catch runaway spend: each individual subagent call can look perfectly reasonable while the run as a whole vastly exceeds any sane ceiling. Cognocient closes that gap with a run-level reservation, shared across every subagent call that carries the same X-Cost-Run-ID, checked atomically before each call fires — so the run's total spend, not just any single call, is what gets enforced.

import uuid
 
async def run_agent(task: str):
    run_id = f"run-{uuid.uuid4()}"   # generate once per agent execution
 
    for step in agent_pipeline(task):
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=step.messages,
            extra_headers={
                "X-Cost-Feature": "my-agent",
                "X-Cost-Run-ID":  run_id,        # same ID for every step in this run
                "X-Cost-Workload": "agentic-write",
            }
        )

Setting an explicit run budget — X-Cost-Run-Budget

Pass X-Cost-Run-Budget alongside X-Cost-Run-ID on any call in the run to declare that run's dollar ceiling. Only the first call Cognocient sees for a given run_id sets the ceiling — every later call (from any subagent, in any order) reads back that same value, so concurrent subagents that start at nearly the same instant still converge on one agreed-upon budget instead of racing to set different limits.

response = client.chat.completions.create(
    model="gpt-4o",
    messages=step.messages,
    extra_headers={
        "X-Cost-Feature":     "research-agent",
        "X-Cost-Run-ID":      run_id,
        "X-Cost-Run-Budget":  "50.00",   # this run's ceiling, in USD
    }
)

If an admin has already configured a per-run budget for this call's feature/department/user scope (see Hierarchical Budgets), that admin-configured ceiling takes precedence over X-Cost-Run-Budget — the header is a fallback for runs that don't fall under any configured budget, not an override.

What happens when a run hits its ceiling

Once a run's cumulative spend would exceed its ceiling, the call that would push it over is rejected with HTTP 429 — every earlier call in the run still succeeded, and calls under a different run_id are unaffected:

{
  "error": {
    "message": "This run has reached its budget ceiling of $50.00 ...",
    "type": "run_budget_exceeded",
    "run_id": "run-9182",
    "run_spend_usd": 50.00,
    "run_limit_usd": 50.00
  }
}

Default run budgets

If a run declares no X-Cost-Run-Budget and no admin-configured per-run budget matches, Cognocient still gives it a ceiling: your account's default run budget, configurable from the Run Budgets dashboard (defaults to $25). This means a run is never left unbounded just because nobody remembered to set a header.

X-Cost-Workload — control what happens when the budget runs out

ROI tracking — X-Cost-Outcome

Add X-Cost-Outcome on calls that produce a measurable business result. This unlocks the AI Investment ROI panel on the dashboard and the Cost/Outcome view in Executive Overview.

# Only set this on calls that confirmed a successful outcome
extra_headers={
    "X-Cost-Feature": "ticket-resolver",
    "X-Cost-Outcome": "ticket-resolved",   # set after the ticket is confirmed resolved
}

The dashboard then shows: cost per ticket resolved, cost per contract drafted, cost per report generated — the ROI number your CFO needs.

See Outcomes & ROI for naming conventions and the full API.

Troubleshooting

No data showing up after I added headers?

1. Make sure you're using your Cognocient proxy key (sk-cog-...), not your OpenAI key directly.
2. Make sure base_url / baseURL points to https://api.cognocient.com/v1.
3. Check the Live Calls tab (/calls) — your call should appear there within seconds. If it does, the headers are working. Dashboard charts update within a few minutes.

Feature names showing up inconsistently?

Attribution is case-sensitive and exact-match. Chatbot and chatbot are different features. Pick a convention (lowercase-hyphen) and stick to it.

Frequently asked questions