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

# OpenClaw Heartbeat

> Ingest an OpenClaw gateway heartbeat with health and token usage

## OpenClaw Heartbeat

The endpoint the OpenClaw daemon posts to on each heartbeat. It records gateway health and token usage for the connection the key is bound to. You normally don't call this yourself — the daemon does — but it's documented here for reference and debugging.

```
POST https://api.opsmatic.com/v1/openclaw/ingest
```

Requires a **`usage-ingestion`** API key scoped to the OpenClaw connection (generated when the connection is created — see [OpenClaw setup](/connections/openclaw-setup)).

### Headers

<ParamField header="Authorization" type="string" required>
  `Bearer ops_...` — must be a `usage-ingestion` key for this connection.
</ParamField>

### Body

<ParamField body="type" type="string" required>
  Heartbeat type emitted by the daemon.
</ParamField>

<ParamField body="gateway" type="object" required>
  Gateway health: `status` (`healthy` / unhealthy), `latencyMs`, `version`.
</ParamField>

<ParamField body="system" type="object">
  Host signals, e.g. `gatewayPidAlive`.
</ParamField>

<ParamField body="tokens" type="object">
  Usage for the period: `period` totals (`inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `requestCount`, `estimatedCostUsd`, `startedAt`, `endedAt`) and an optional `byModel` breakdown.
</ParamField>

<Note>
  Ingestion is **idempotent** — retrying the same heartbeat is safe and won't double-count. When a `byModel` entry omits `estimatedCostUsd`, Opsmatic prices the token counts server-side using its [pricing table](/connections/openclaw-setup#how-costs-are-calculated).
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.opsmatic.com/v1/openclaw/ingest \
    -H "Authorization: Bearer ops_usage_ingestion_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "heartbeat",
      "gateway": { "status": "healthy", "latencyMs": 42, "version": "1.4.0" },
      "system": { "gatewayPidAlive": true },
      "tokens": {
        "period": {
          "inputTokens": 128000,
          "outputTokens": 34000,
          "cacheReadTokens": 8000,
          "cacheWriteTokens": 0,
          "requestCount": 57,
          "estimatedCostUsd": 1.42,
          "startedAt": "2026-07-06T00:00:00Z",
          "endedAt": "2026-07-06T01:00:00Z"
        },
        "byModel": [
          { "model": "claude-sonnet-4-5", "inputTokens": 128000, "outputTokens": 34000 }
        ]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  { "message": "Heartbeat recorded", "heartbeat_id": "hb_abc123" }
  ```

  ```json 403 theme={null}
  { "error": "API key role must be usage-ingestion" }
  ```

  ```json 413 theme={null}
  { "error": "Payload too large" }
  ```
</ResponseExample>