Track spend per end customer

If you serve many customers of your own, your AI spend is the sum of what each of them used. A customer tag records that on every call, so you can read spend per customer straight from the API.

1. Choose the ID

Use the stable ID you already have for an account or workspace, such as client-0482. It can be up to 128 printable characters. If you prefer not to send real identifiers, send a hash or an internal number; the tag is only ever shown to your organisation.

2. Tag every call

For tasks, use the customer field:

{
  "model": "image/demo-1",
  "input": { "prompt": "Studio shot of a leather wallet", "n": 4 },
  "customer": "client-0482"
}

For chat, or any request, use the header:

X-Tovano-Customer: client-0482

If both are present, the customer field wins. With the SDK, pass customer to tasks.create or tasks.run.

The simplest way to never forget the tag is to set it in the one place your code calls Tovano, for example a small wrapper that takes the current account from the request context.

3. Read spend per customer

curl "https://api.tovano.ai/v1/usage?group_by=customer&from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $TOVANO_API_KEY"

{
  "object": "usage",
  "group_by": "customer",
  "from": "2026-11-01",
  "to": "2026-11-30",
  "total_micro": 48210440000,
  "data": [
    { "key": "client-0482", "tasks": 1820441, "failed": 312, "charged_micro": 9120400000 },
    { "key": "client-0517", "tasks": 940112, "failed": 87, "charged_micro": 5288030000 }
  ]
}

from and to are inclusive dates. Without them you get the current month. A row with an empty key collects calls sent without a tag.

To see one customer by model, filter and group again:

curl "https://api.tovano.ai/v1/usage?group_by=model&customer=client-0482" \
  -H "Authorization: Bearer $TOVANO_API_KEY"

4. Feed your own billing

A nightly job that reads yesterday's spend per customer and writes it to your billing system is usually enough:

import { Tovano } from "tovano";

const tovano = new Tovano();
const day = new Date(Date.now() - 86_400_000).toISOString().slice(0, 10);

const usage = await tovano.usage({ group_by: "customer", from: day, to: day });
for (const row of usage.data) {
  if (!row.key) continue;
  await billing.recordUsage({ account: row.key, date: day, costMicro: row.charged_micro });
}

Keep amounts in micro-dollars until you produce your own invoice. See Why every amount in our API is an integer.

5. In the dashboard

Usage shows the same numbers grouped by customer, model, day, project or API key, with a CSV export for finance.

Tips

• Separate environments with projects, not tags. Use one project per product or environment, and tags for your end customers.
• Watch the failed column. A customer with many failed tasks often sends input your product should validate first. Failed tasks are never charged, but they slow that customer down.