Usage - WireSocket

The Usage endpoint returns a live snapshot of your application’s current concurrent connections and active documents across the entire WireSocket network. Use this to power admin dashboards, monitor limits, and trigger upgrade prompts before users hit hard limits.

Endpoint

GET https://{region}.ws.wiresocket.com/usage

Authentication

Pass your JWT using one of the following:

Method	How
Authorization header (recommended)	`Authorization: Bearer YOUR_ACCESS_TOKEN`
Query parameter	`?token=YOUR_ACCESS_TOKEN`

The JWT identifies both the tenant and application. This endpoint is safe to call directly from the browser — users will only ever see their own application’s data.

Response

{
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "appId": "770k8400-f29b-41d4-b716-556655449999",
  "usage": {
    "connections": {
      "current": 82,
      "limit": 100,
      "percent": 82.0,
      "status": "warning"
    },
    "documents": {
      "current": 4,
      "limit": 20,
      "percent": 20.0,
      "status": "healthy"
    }
  },
  "timestamp": "2026-02-25T14:40:00.000Z"
}

Field	Type	Description
`usage.connections.current`	number	Total active WebSocket connections across all regions
`usage.connections.limit`	number	Your plan’s `maxConnections` value
`usage.connections.percent`	number	Current usage as a percentage of limit
`usage.connections.status`	string	`healthy` below 75%, `warning` 75–89%, `critical` 90% and above
`usage.documents.current`	number	Total unique documents currently being synced
`usage.documents.limit`	number	Your plan’s `maxDocuments` value
`timestamp`	string	UTC timestamp of the snapshot

Error Responses

Status	Description	What To Do
`401`	JWT is missing or invalid	Re-authenticate and retry with a fresh token
`429`	Rate limit exceeded	Back off — this endpoint allows 12 requests per minute
`503`	Node degraded or overloaded	Retry with backoff using the `Retry-After` header

Recommendations

Poll no more than once per minute for admin dashboards — the STRICT rate limit allows up to once every 5 seconds but once per minute is sufficient for most use cases
Use percent and status to drive progress bars or color-coded health indicators
Trigger an upgrade prompt when status reaches warning to prevent users hitting hard limits in production

Last modified on February 25, 2026