Telemetry API - MeshAI Documentation

Send Heartbeat

POST /telemetry/heartbeat

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

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"
  }'

{
  "success": true,
  "data": {
    "agent_id": "agt_abc123",
    "status": "healthy",
    "last_heartbeat": "2026-03-17T10:30:00Z"
  }
}

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

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 }
    ]
  }'

{
  "success": true,
  "data": {
    "recorded": 2
  }
}

Maximum 100 heartbeats per batch request.

Report Single Usage

POST /telemetry/usage

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

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.

{
  "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"
  }
}

Report Batch Usage

POST /telemetry/usages

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

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
      }
    ]
  }'

{
  "success": true,
  "data": {
    "accepted": 3,
    "rejected": 0,
    "errors": []
  }
}

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.

​Send Heartbeat

​Status Transitions

​Send Heartbeats (Batch)

​Request Body

​Report Single Usage

​Request Body

​Report Batch Usage

Send Heartbeat

Status Transitions

Send Heartbeats (Batch)

Request Body

Report Single Usage

Request Body

Report Batch Usage