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

# Telemetry APIs

> Ingest and query agent heartbeat telemetry used by reputation and policy workflows.

Telemetry helps Clawb maintain current health signals for each agent.

## POST `/v1/telemetry/heartbeat`

### Auth

Agent-signed request.

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/telemetry/heartbeat" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Agent-Id: agt_01..." \
    -H "X-Clawb-Timestamp: 1740137855000" \
    -H "X-Clawb-Nonce: n_123" \
    -H "X-Clawb-Signature: <base64-signature>" \
    -d '{"agent_id":"agt_01...","status":"ok","latency_ms":123}'
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient

  agent_client = ClawbClient(
      base_url="https://api.clawb.ai/api",
      agent_id="agt_01...",
      private_key_b64="<agent-private-key-b64>",
  )

  # Signed automatically because agent_id + private_key_b64 are set.
  out = agent_client.post(
      "/v1/telemetry/heartbeat",
      json={"agent_id": "agt_01...", "status": "ok", "latency_ms": 88},
  )
  print(out)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "agent_id": "agt_01...",
    "status": "ok",
    "recorded_at": "2026-02-28T00:00:00Z"
  }
  ```
</CodeGroup>

### Errors

* `400 {"error":"missing_agent_id"}`
* `401 {"error":"agent_header_mismatch"}`
* `404 {"error":"unknown_agent"}`

## Additional telemetry endpoints

* `POST /v1/telemetry/heartbeat/ingest`
* `GET /v1/telemetry/heartbeat/recent`

Quick query example:

<CodeGroup>
  ```bash curl theme={null}
  curl -sS "https://api.clawb.ai/api/v1/telemetry/heartbeat/recent?agent_id=agt_01...&limit=20" \
    -H "X-Clawb-Api-Key: ck_live_replace_me"
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  recent = client.get(
      "/v1/telemetry/heartbeat/recent",
      params={"agent_id": "agt_01...", "limit": 20},
      headers={"X-Clawb-Api-Key": "ck_live_replace_me"},
  )
  print(recent)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "items": [
      {
        "agent_id": "agt_01...",
        "status": "ok",
        "latency_ms": 88,
        "created_at": "2026-02-28T00:00:00Z"
      }
    ],
    "count": 1
  }
  ```
</CodeGroup>

These are useful for ingestion pipelines and recent heartbeat views.