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

# Per-Customer Cost

> Attribute LLM spend to each end-customer so you know the margin behind every account.

**Know exactly what each customer costs you in LLM spend by tagging requests with their ID.**

<Steps>
  <Step title="Tag every request with a customer identifier">
    Pass your customer's identifier as a metadata key using `X-Toolken-Metadata-Customer-Id`. The header suffix maps directly to the `customer_id` metadata key in the dashboard. Use whatever ID you already have -- a user ID, an org slug, or an account number.

    <CodeGroup>
      ```python Python theme={null}
      from openai import OpenAI

      client = OpenAI(
          base_url="https://gateway.toolken.ai/v1",
          api_key="sk-...",  # your provider key, forwarded untouched
          default_headers={
              "X-Toolken-Key": "tk_live_...",
              "X-Toolken-Metadata-Customer-Id": "cust_acme",
          },
      )
      client.chat.completions.create(
          model="gpt-4o-mini",
          messages=[{"role": "user", "content": "Generate a project summary."}],
      )
      ```

      ```javascript Node theme={null}
      import OpenAI from "openai";

      const client = new OpenAI({
        baseURL: "https://gateway.toolken.ai/v1",
        apiKey: process.env.OPENAI_API_KEY, // forwarded untouched
        defaultHeaders: {
          "X-Toolken-Key": "tk_live_...",
          "X-Toolken-Metadata-Customer-Id": "cust_acme",
        },
      });
      await client.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [{ role: "user", content: "Generate a project summary." }],
      });
      ```

      ```bash curl theme={null}
      curl https://gateway.toolken.ai/v1/chat/completions \
        -H "Authorization: Bearer $OPENAI_API_KEY" \
        -H "X-Toolken-Key: tk_live_..." \
        -H "X-Toolken-Metadata-Customer-Id: cust_acme" \
        -H "Content-Type: application/json" \
        -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Generate a project summary."}]}'
      ```
    </CodeGroup>
  </Step>

  <Step title="Open the dashboard and group by Customer">
    Go to the cost view in the dashboard. Use the "Group by" control to select **Customer**. Each customer ID appears as a row showing cost, token usage, and request count.

    <Frame caption="Cost grouped by customer">
      <img src="https://mintcdn.com/toolken/B9FQGhQVN-q79Dqo/images/cost-by-customer.png?fit=max&auto=format&n=B9FQGhQVN-q79Dqo&q=85&s=df578bc8bb29b74d86113ed1a2d76887" alt="Dashboard showing cost broken down by customer" width="1440" height="900" data-path="images/cost-by-customer.png" />
    </Frame>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Set customer via metadata (precedence)">
    You can set the customer dimension in more than one way on the same request. If you send multiple, the highest-priority one wins:

    | Priority    | Method                                                                 |
    | ----------- | ---------------------------------------------------------------------- |
    | 1 (highest) | `"customer_id"` key inside the provider request body `metadata` object |
    | 2           | `X-Toolken-Metadata: {"customer_id":"<id>"}`                           |
    | 3 (lowest)  | `X-Toolken-Metadata-Customer-Id: <id>`                                 |

    Pick one method and stay consistent. The priority only matters when you accidentally set it multiple ways.
  </Accordion>

  <Accordion title="Cost per customer per agent">
    Add `X-Toolken-Metadata-Agent` alongside `X-Toolken-Metadata-Customer-Id` to get a two-dimensional view. You can then answer questions like "how much did `cust_acme` spend on the `report-generator` agent this month?".

    ```python theme={null}
    default_headers={
        "X-Toolken-Key": "tk_live_...",
        "X-Toolken-Metadata-Customer-Id": "cust_acme",
        "X-Toolken-Metadata-Agent": "report-generator",
    }
    ```

    Group by **Customer** then by **Agent** in the dashboard to see the breakdown.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Cost Per Agent" icon="robot" href="/use-cases/cost-per-agent">Break down spend by agent or workflow.</Card>
  <Card title="Cost by Environment" icon="server" href="/use-cases/cost-by-environment">Separate production and staging spend.</Card>
</CardGroup>