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

# Telemetry API

> Send heartbeats and report token usage

## Send Heartbeat

```
POST /telemetry/heartbeat
```

Report that an agent is alive. Updates the agent's `last_heartbeat` timestamp and sets status to `healthy`.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/telemetry/heartbeat \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent_id": "agt_abc123",
      "status": "healthy",
      "last_heartbeat": "2026-03-17T10:30:00Z"
    }
  }
  ```
</ResponseExample>

### Status Transitions

| Condition                           | Status     |
| ----------------------------------- | ---------- |
| Heartbeat received within 2 minutes | `healthy`  |
| No heartbeat for 2–5 minutes        | `degraded` |
| No heartbeat for 5+ minutes         | `down`     |
| Never sent a heartbeat              | `unknown`  |

## Send Heartbeats (Batch)

```
POST /telemetry/heartbeats
```

Report multiple agent heartbeats in a single request. Requires the `telemetry:write` scope.

### Request Body

| Field        | Type  | Required | Description                                                            |
| ------------ | ----- | -------- | ---------------------------------------------------------------------- |
| `heartbeats` | array | Yes      | Up to 100 heartbeat objects, same shape as `POST /telemetry/heartbeat` |

Each heartbeat object:

| Field        | Type    | Required | Description                                 |
| ------------ | ------- | -------- | ------------------------------------------- |
| `agent_id`   | string  | Yes      | Agent ID                                    |
| `status`     | string  | Yes      | `healthy`, `degraded`, `down`, or `unknown` |
| `latency_ms` | integer | No       | Latency in milliseconds (0-3,600,000)       |
| `metadata`   | object  | No       | Arbitrary key-value metadata                |

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/telemetry/heartbeats \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "heartbeats": [
      { "agent_id": "agt_abc123", "status": "healthy", "latency_ms": 120 },
      { "agent_id": "agt_def456", "status": "degraded", "latency_ms": 850 }
    ]
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "recorded": 2
    }
  }
  ```
</ResponseExample>

Maximum **100 heartbeats** per batch request.

## Report Single Usage

```
POST /telemetry/usage
```

Report a single LLM API call with token counts and optional cost.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/telemetry/usage \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "model_provider": "openai",
    "model_name": "gpt-4o",
    "input_tokens": 1500,
    "output_tokens": 800,
    "request_type": "chat.completions",
    "cost_usd": 0.035
  }'
```

### Request Body

| Field            | Type    | Required | Description                                                |
| ---------------- | ------- | -------- | ---------------------------------------------------------- |
| `agent_id`       | string  | Yes      | Agent ID                                                   |
| `model_provider` | string  | Yes      | `openai`, `anthropic`, `google`, `nvidia`, `bedrock`       |
| `model_name`     | string  | Yes      | Model identifier (e.g., `gpt-4o`)                          |
| `input_tokens`   | integer | Yes      | Input/prompt token count                                   |
| `output_tokens`  | integer | Yes      | Output/completion token count                              |
| `request_type`   | string  | No       | e.g., `chat.completions`, `embeddings`                     |
| `cost_usd`       | float   | No       | Explicit cost. If omitted, calculated from pricing tables. |

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "usg_abc123",
      "agent_id": "agt_abc123",
      "model_provider": "openai",
      "model_name": "gpt-4o",
      "input_tokens": 1500,
      "output_tokens": 800,
      "cost_usd": 0.035,
      "recorded_at": "2026-03-17T10:30:00Z"
    }
  }
  ```
</ResponseExample>

## Report Batch Usage

```
POST /telemetry/usages
```

Report multiple usage events in a single request. More efficient than sending individual events.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/telemetry/usages \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usages": [
      {
        "agent_id": "agt_abc123",
        "model_provider": "openai",
        "model_name": "gpt-4o",
        "input_tokens": 1500,
        "output_tokens": 800
      },
      {
        "agent_id": "agt_abc123",
        "model_provider": "openai",
        "model_name": "gpt-4o-mini",
        "input_tokens": 500,
        "output_tokens": 200
      },
      {
        "agent_id": "agt_def456",
        "model_provider": "anthropic",
        "model_name": "claude-sonnet-4-20250514",
        "input_tokens": 2000,
        "output_tokens": 1200
      }
    ]
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "accepted": 3,
      "rejected": 0,
      "errors": []
    }
  }
  ```
</ResponseExample>

Maximum **100 events** per batch request. Events that fail validation are reported in the `errors` array but do not block the rest of the batch.