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

# Send realtime spend

> Push usage-based spend from your own applications with a write-only ingest key.

Your applications can report spend that no billing export carries, such as LLM tokens through
your own gateway or per-request database charges, as it happens. Cloud Capital stores it with
your other cost data, so it appears in Cost Insights and forecasts after the nightly load.

### Setup

**1. Create the integration**

Choose **Realtime Spend**. The integration starts as a draft. A draft checks and counts the rows
you send, then discards them, so you can test without adding spend.

**2. Create an ingest key**

Select **Create key** and copy the key. It is shown once. An ingest key can only send spend to
this integration and cannot read anything; keep it in your server-side configuration.

**3. Send a test row**

Run the curl command the page shows. The page's **Activity** section shows the rows it has
received.

**4. Enable**

Set the status to **Enabled** and save. Spend loads into your cost data each night.

### Sending spend

`POST` a JSON array of 1 to 100 rows to the endpoint on the integration page, with
`Authorization: Bearer <ingest key>`.

```bash theme={null}
curl -X POST https://ingest.cloudcapital.co/v1/ingest \
  -H "Authorization: Bearer $CC_INGEST_KEY" \
  -H 'content-type: application/json' \
  -d '[{"timestamp":"2026-11-20T12:00:00Z","vendor":"OpenAI","service":"chat.completions","usage_unit":"tokens","cost":0.0123,"usage":1840}]'
```

| Field | Required | Meaning |
| - | - | - |
| `timestamp` | yes | When the spend happened, ISO-8601 with a time zone. From the start of last month up to 5 minutes ahead. |
| `vendor` | yes | Who charged for it, such as `OpenAI`. Shown as the cloud in Cost Insights. |
| `service` | yes | What was used, such as `chat.completions`. |
| `usage_unit` | yes | The unit of `usage`, such as `tokens`. Usage is summed per unit. |
| `cost` | yes | Cost in USD, zero or more. Negative only for credits (see below). |
| `usage` | yes | Quantity used, in `usage_unit`. |
| `resource_family` | no | A grouping within the service. Defaults to `service`. |
| `region` | no | Region, if the spend has one. |
| `instance_type` | no | A sub-type, such as a model name. |
| `usage_type` | no | A detailed description of the usage. |
| `resource_tags` | no | Your tags, as string keys and values (at most 50). Keys may not start with `cc:`. |
| `cost_type` | no | Defaults to `On Demand Usage`. |

**Credits and refunds** use `cost_type: "Credit"` with a negative `cost`. They lower your spend
and show as savings.

### Responses

A `200` response lists what was accepted. Valid rows are stored even when others in the batch are
rejected; each rejected row is listed with its position and the field that failed.

`countsByDimension` counts every row this integration has accepted, by vendor, service and
usage unit. It lists the 1,000 most counted values of each.

```json theme={null}
{
  "accepted": 1,
  "rejected": 0,
  "rejections": [],
  "countsByDimension": { "vendor": { "OpenAI": 1 }, "service": { "chat.completions": 1 }, "usage_unit": { "tokens": 1 } },
  "lastReceived": "2026-11-20T12:00:01.000Z"
}
```

| Status | Meaning |
| - | - |
| `400` | The body is not a JSON array of 1 to 100 rows, or the `Idempotency-Key` is malformed. Nothing was stored. |
| `401` | The key is missing, malformed, unknown or revoked, or the integration is disabled. The `code` says which. |
| `413` | The body is larger than 512 KB. |
| `422` | The `Idempotency-Key` was already used with a different body. Nothing was stored. |
| `503` | The key could not be checked. Retry the request. |

### Retries

If a call times out or fails, you cannot tell whether its rows were stored. Retrying it without
an idempotency key can store them twice and double-count that spend. Send an `Idempotency-Key`
header on each call, such as a new UUID, and reuse it when you retry that call:

```bash theme={null}
IDEMPOTENCY_KEY=$(uuidgen)   # once per batch; reuse it when you retry that batch
curl -X POST https://ingest.cloudcapital.co/v1/ingest \
  -H "Authorization: Bearer $CC_INGEST_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'content-type: application/json' \
  -d @batch.json
```

For 24 hours, a retry with the same key and body returns the first response and stores nothing
new. The response then has the header `Idempotency-Replayed: true`. Use a new key for each new
batch.

### Keys

Rotate a key from the integration page: the new key is shown once and the old one stops working
within a minute. Revoking works the same way.


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