API reference

Usage & metrics

Daily usage, current quotas and circuit-breaker state with GET /v0/usage, and metrics endpoints for events, usage and rates.

docs.simail.ai/api/usage

Usage

GET/v0/usage

Permission usage_read. Query from and to (dates, YYYY-MM-DD, UTC; default the last 7 days).

{
  "organization_id": "org_01JZX3S5V7W9X1Y3Z5A7B9C1D3",
  "days": [
    { "date": "2026-10-18", "received": 41, "sent_messages": 12, "sent_recipients": 14, "bounced": 0, "complained": 0, "storage_bytes": 18734120, "api_calls": 2210 }
  ],
  "quotas": {
    "inbox_limit": 10,
    "daily_recipients": 100,
    "daily_recipients_used": 14,
    "api_calls_daily": 50000
  },
  "breaker": { "state": "ok", "reason": null, "bounce_rate_7d": 0.0, "complaint_rate_7d": 0.0 }
}

breaker.state is ok or tripped. When it is tripped, reason says why (for example message.bounced) and sending stays paused until a human resumes it. See circuit breakers. Counts never include message content.

MCP: get_usage returns the same object, including the breaker reason.

Metrics

GET/v0/metrics/events

GET/v0/metrics/usage

GET/v0/metrics/rates

Permission usage_read. Time series for charts and alerts: event counts by type, usage counters by day, and send, bounce and complaint rates. Each takes from, to and, where it applies, types. Inbox and pod variants (/v0/inboxes/{inbox_id}/metrics/…, /v0/pods/{pod_id}/metrics/…) narrow the series.