Ingram Cloud
Sign inGet started

Documentation

Usage, cost & budgets

OpenAPI spec
Docs

Usage, cost & budgets

Watch what this project consumes (tokens, runs, cost) and cap it. This page is about what each project spends; invoicing your own customers is Customers & metering, and topping up the org wallet those projects draw from is Credits & billing.

What's measured

Every run records token usage; every model call lands in a trace with a computed cost (token counts × a per-model price book, in EUR). The same figure is what the run debits from your org's credit wallet (times any platform margin), so usage you see here and credits you spend there move together.

Reading usage

Totals and a per-day series:

# Authorization: tenant-admin token (server-side only)
curl https://api.cloud.ingram.tech/v1/tenant/usage
# → { "totals": { "runs": …, "input_tokens": …, "output_tokens": …, "total_tokens": … },
#     "series": [ { "date": "2026-06-10", "runs": …, "total_tokens": … }, … ] }

Cost rollups, grouped and filterable:

# Authorization: tenant-admin token (server-side only)
curl "https://api.cloud.ingram.tech/v1/usage?group_by=smith&period=2026-06"
# group_by: app | smith | model | customer
# filters:  from / to (dates), period (YYYY-MM), smith_id, customer_id
# format=csv exports the table
# → { "totals": { "tokens": …, "cost": …, "run_count": … },
#     "groups": [ { "smith": "smt_…", "tokens": …, "cost": …, "run_count": … } ] }

The console's Observe → Usage & cost renders the same numbers: stat cards, budgets, the usage-over-time chart, and top consumers by smith/model/app.

BYOK model-provider keys

Smiths run on your own keys, per project: Settings → Models, or

# Authorization: tenant-admin token (server-side only)
curl -X PUT https://api.cloud.ingram.tech/v1/tenant/model_keys/anthropic \
  -H "Authorization: Bearer $IC_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "sk-ant-…" }'        # optional: "base_url" for proxies

Keys are encrypted at rest and never returned by reads (GET /v1/tenant/model_keys shows presence only). The model catalog (GET /v1/tenant/models) marks which models are runnable with the keys you have; a run that resolves to a keyless provider fails with model_key_missing.

Budgets

A budget caps monthly spend for a scope and acts when crossed. limit_usd is the cap in your billing currency (EUR):

# Authorization: tenant-admin token (server-side only)
curl -X POST https://api.cloud.ingram.tech/v1/budgets \
  -H "Authorization: Bearer $IC_TOKEN" \
  -H "IC-Api-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "tenant", "limit_usd": 100, "action": "block" }'
# scope: "tenant" (whole project) | "smith" + scope_id | "customer" + scope_id
# action: "warn" | "block"
  • Crossing 80% and 100% emits a budget.threshold event (once per tier per month). Wire it to a webhook for alerts.
  • A block budget at 100% rejects new runs with 402 budget_exceeded until the month rolls over or the limit is raised. warn only notifies.
  • GET /v1/budgets/{id}/status returns spend-to-date, percent, and whether it's over; the console shows the same as cards at the top of Usage & cost.

Budget checks run at run creation against the current calendar month (UTC).

The tenant budget is the project's funding cap

A tenant-scope budget is special: it bounds how much this project may draw from the org's shared credit wallet in the month. Without one, a project draws freely up to the org's overall balance; with a block one, it stops at its own limit even while the wallet still has funds. Two independent gates, both at run creation: the project budget (402 budget_exceeded) and the empty wallet (402 insufficient_credits).

Events & webhooksCustomers & metering