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

# Send custom gateway usage

> Send unpriced model usage through the API or Prometheus remote write for CostGraph to price and attribute

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](https://docs.costgraph.ai/costgraph/integrations/ai-gateways.md#connect-your-gateway)
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](https://docs.costgraph.ai/costgraph/integrations/ai-gateways.md#how-usage-is-priced).

The following request sends 20,000 output tokens for one model. Replace the
connection ID and charge period with your values.

```bash theme={null}
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](https://docs.costgraph.ai/costgraph/integrations/focus-push.md) 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.

```text theme={null}
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](#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](#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](https://docs.costgraph.ai/costgraph/integrations/ai-gateways.md#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](https://docs.costgraph.ai/costgraph/integrations/ai-gateways.md#model-map).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.