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

# Workload Tags

> Name the workload behind each request so usage and spend split by job, not just by model

## Why tag requests

Usage reporting groups by model. If you run invoice extraction and support-ticket triage against the same model, their spend lands in one bucket and you cannot tell which job costs what, or which one started failing.

A workload tag fixes that. Send an optional name with each request and Valar records it on the usage ledger, so every job gets its own line in usage and spend even when several jobs share a model.

## How it works

Send a `valar_workload` key inside the request's `metadata` object:

<CodeGroup>
  ```python theme={"system"}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.valarhq.ai/v1", # or read OPENAI_BASE_URL from the environment
      api_key="YOUR_VALAR_API_KEY",  # or read OPENAI_API_KEY from the environment
  )

  response = client.chat.completions.create(
      model="google/gemini-3.1-flash-lite",
      messages=[{"role": "user", "content": "Extract the total from this invoice."}],
      metadata={"valar_workload": "invoice-extraction"},
  )
  ```

  ```bash theme={"system"}
  curl https://api.valarhq.ai/v1/responses \
    -H "Authorization: Bearer $VALAR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "google/gemini-3.1-flash-lite",
          "input": "Extract the total from this invoice.",
          "metadata": {"valar_workload": "invoice-extraction"}
        }'
  ```
</CodeGroup>

That's it. There is nothing to pre-register: the first tagged request creates the workload in your reporting.

## Rules

<ParamField path="Optional" type="default: untagged">
  Omit the key and nothing changes. Untagged requests are recorded exactly as before and
  appear as one "Untagged" bucket in the dashboard.
</ParamField>

<ParamField path="Names are normalized" type="lowercase slug, max 64 chars">
  Tags are lowercased, whitespace becomes `-`, and anything outside `a-z 0-9 . _ -` is
  dropped. So `"Invoice Extraction"` and `"invoice-extraction"` are the same workload. A
  caller who types a human name and one who sends a slug agree instead of splitting spend
  across two buckets.
</ParamField>

<ParamField path="Names are the join key" type="keep them stable">
  Reporting joins on the normalized name across time. Renaming a workload starts a new one;
  the old name keeps its history.
</ParamField>

<ParamField path="Never affects results" type="label only">
  The tag does not change routing, model selection, price, or output. The `metadata` echoed
  back on the response is byte-identical to what you sent, original casing included.
</ParamField>

## Where you see it

Open **Usage & Billing** in the dashboard and switch the Breakdown to **Workload**. Each workload shows its responses, tokens, success rate, latency (p50/p99), and spend over the last 30 days, for the selected workspace or across your whole organization. The view exports to CSV like the other breakdowns.