Channel Queries

Query channel information and statistics

Get Channels List

GET · endpoint

Retrieve a list of all active channels for an application

Authentication

Same authentication requirements as Trigger Event.

Path Parameters

appId · string · required

The application ID

Query Parameters

filter_by_prefix · string

Filter channels by name prefix (e.g., presence- for only presence channels)

info · string

Comma-separated attributes to include:

• user_count - Number of unique users (presence channels only)

Note: When requesting user_count without filter_by_prefix=presence-, an error is returned if non-presence channels exist.

Plus standard authentication query parameters (auth_key, auth_timestamp, auth_version, auth_signature).

Response

channels · object

Object with channel names as keys and channel info as values

Show Channel Info

user_count · number

Number of unique users (only when info=user_count and channel is presence type)

Channels with no info requested return empty object {}.

Examples

All Channels

curl "https://api.example.com/apps/my-app/channels?auth_key=key&auth_timestamp=1234567890&auth_version=1.0&auth_signature=abc123"

Response Examples

All Channels (No Info)

{
  "channels": {
    "orders": {},
    "inventory": {},
    "presence-lobby": {}
  }
}

---

Get Channel Info

GET · endpoint

Retrieve detailed information about a specific channel

Authentication

Same authentication requirements as Trigger Event.

Path Parameters

appId · string · required

The application ID

channelName · string · required

The channel name

Query Parameters

info · string

Comma-separated attributes to include:

• subscription_count - Number of active subscriptions
• user_count - Number of unique users (presence channels only)
• cache - Cached event data (cache channels only)

Plus standard authentication query parameters.

Response

occupied · boolean

Whether the channel has any active subscriptions

subscription_count · number

Number of active subscriptions (when info includes subscription_count)

user_count · number

Number of unique users (when info includes user_count and channel is presence type)

cache · object

Cached event data (when info includes cache and channel starts with cache-)

Show Cache Data

event · string

Cached event name

channel · string

Channel name

data · string | object

Cached event data

ttl · number

Time-to-live in seconds

Examples

Basic Info

curl "https://api.example.com/apps/my-app/channels/orders?auth_key=key&auth_timestamp=1234567890&auth_version=1.0&auth_signature=abc123"

Response Examples

Basic (No Info)

{
  "occupied": true
}

Rate Limiting

Same rate limit headers as single event endpoint.

Error Codes

Status Code	Description
200	Success
400	Bad Request (invalid channel name, invalid info parameter)
401	Unauthorized (authentication failed)
404	Application not found
500	Internal Server Error

Notes

• Channel names must follow validation rules (no spaces, special character restrictions)
• Only occupied channels (with active subscriptions) are returned in the channels list
• user_count is only available for presence channels (those starting with presence-)
• Cache channels (cache-*) store the last published event for 1 hour (3600 seconds TTL)
• Empty channels are automatically cleaned up by the system