Skip to main content

​
Send Heartbeat

POST /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/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

ConditionStatus
Heartbeat received within 2 minuteshealthy
No heartbeat for 2–5 minutesdegraded
No heartbeat for 5+ minutesdown
Never sent a heartbeatunknown

​
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/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

FieldTypeRequiredDescription
agent_idstringYesAgent ID
model_providerstringYesopenai, anthropic, google, nvidia, bedrock
model_namestringYesModel identifier (e.g., gpt-4o)
input_tokensintegerYesInput/prompt token count
output_tokensintegerYesOutput/completion token count
request_typestringNoe.g., chat.completions, embeddings
cost_usdfloatNoExplicit 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/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.