realtime-events

Get a Realtime channel

Returns a single channel's occupancy and optional counts. A channel appears when its first connection subscribes and disappears when its last connection leaves. An unknown or unused name returns 200 OK with occupied: false.

get/v1/realtime/apps/{realtime_app_id}/channels/{channel_name}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/realtime/apps/{realtime_app_id}/channels/{channel_name}
  • Auth: one of:
    • HTTP bearer and API key in header X-Realtime-Key and API key in header X-Realtime-Secret
    • API key in cookie bird_session and API key in header X-Realtime-Key and API key in header X-Realtime-Secret

Query parameters

includeRealtimeChannelInclude[]

Attributes to include. Repeatable. Requesting member_count for a non-presence channel, or connection_count when the app's connection-counting flag is off, returns a validation error (400).

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The channel state.

member_countinteger

Distinct members (presence channels only; requires include=member_count).

connection_countinteger

Connections currently subscribed to this channel (requires include=connection_count and the app's connection-counting flag). Channel-scoped: distinct from the app-wide peak connections metric.

occupiedboolean required

Whether at least one client is subscribed.

Changes

No recorded changes to this operation across all 3 revisions of this API.