Send custom gateway usage - CostGraph Documentation

Send model usage from your own collector when the CostGraph operator or agent does not scrape your gateway. CostGraph prices token usage and includes it in Cost breakdown alongside your other costs. Create an AI gateway connection and select Neither under Where it runs. Choose the ingestion format that matches your collector.

Send usage through the API

Use an API key with focus:write and the connection’s UUID. Send FOCUS 1.2 rows with usage quantities and no cost fields. CostGraph calculates the cost using the connection’s model rates. The following request sends 20,000 output tokens for one model. Replace the connection ID and charge period with your values.

curl -X POST https://api.costgraph.ai/api/v1/tenant/billing/focus/usage \
  -H "Authorization: Bearer $COSTGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "connection_id": "00000000-0000-0000-0000-000000000000",
  "focus_version": "1.2",
  "charge_period_start": "2026-11-12T00:00:00Z",
  "charge_period_end": "2026-11-13T00:00:00Z",
  "rows": [{
    "SkuId": "meta/llama-3.3-70b",
    "SkuMeter": "meta/llama-3.3-70b/output",
    "ConsumedQuantity": "20000",
    "ConsumedUnit": "tokens"
  }]
}
JSON

Rows containing BilledCost, EffectiveCost, ListCost, or ContractedCost are rejected. If your collector calculates costs, use Push FOCUS data to send priced records.

Send Prometheus metrics

Send the costgraph_gen_ai_usage_total counter through Prometheus remote write to https://tsdb.costgraph.ai/api/v1/write. Include your API key in the X-API-Key header. Prometheus, OpenTelemetry Collector, and Grafana Alloy can send these metrics. The counter records cumulative units consumed. This example reports 20,000 input tokens attributed to the customer acme. Replace the tenant ID and gateway name with the values from your connection.

costgraph_gen_ai_usage_total{costgraph_tenant_id="00000000-0000-0000-0000-000000000000",costgraph_gateway="prod-inference",costgraph_model="gpt-4o",costgraph_usage_kind="input",costgraph_unit="tokens",costgraph_sub_account="acme",costgraph_host="openai"} 20000

Supported labels

The required labels identify the connection and the usage to price.

Required label	Value
`costgraph_tenant_id`	Your CostGraph tenant ID.
`costgraph_gateway`	The gateway name set on the connection.
`costgraph_model`	The reported model identifier. A model map can translate it to a catalog model.
`costgraph_usage_kind`	The type of usage, such as `input` or `output`. See Usage kinds.
`costgraph_unit`	`tokens`, `images`, `seconds`, or `characters`. Only tokens are priced.

Optional labels add attribution and pricing context.

Optional label	Value
`costgraph_sub_account`	The customer identifier stored in the FOCUS sub-account fields.
`costgraph_host`	The model host, such as `openai` or `anthropic`. Rate lookup prefers a price for this host.
`costgraph_input_includes_cache`	Whether the input count includes cached tokens. See Cached token accounting.
`costgraph_cluster_id`, `costgraph_cluster_name`	The cluster that runs the gateway. Omit these for sources outside Kubernetes.

CostGraph skips series with missing required labels, unknown usage kinds or units, or values of zero or less. Both the tenant ID and gateway name must match the connection. Use Attribution spec to read other labels, such as team or route, into cost dimensions. These labels do not need a costgraph_ prefix.

Usage kinds

The accepted usage kinds are input, output, cached_input, cache_write, reasoning, image, audio_input, audio_output, and embedding. CostGraph also accepts input_cache_read as cached_input and input_cache_write as cache_write.

Cached token accounting

Set costgraph_input_includes_cache="true" when your input count includes the cached input and cache-write tokens you report separately. CostGraph subtracts these from input to avoid counting them twice. Without this label, CostGraph uses the host’s convention. Anthropic, Bedrock, and Claude on Vertex report cached tokens separately from input. Other hosts include them in input.

Verify imported usage

Allow up to an hour for processing. Open Cost breakdown, select the tenant and date range, and group by Provider. Check the gateway’s token quantity and cost. Enable Columns > Show zero cost to see usage without a matching rate. If usage is missing, check the connection identifiers and required labels. If quantity appears without a cost, check the model mapping and rates.