Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Channel Status API


The Channel Status API is part of the Channel Metadata API, and provides the capability to access information about channels via our REST endpoint. The information includes the current state of a channel, or the current occupancy data. This data can be accessed as follows:

- Requesting the channel status of a single channel.
- Enumerating all currently active channels within an app, optionally providing the channel status of each enumerated channel.

At present, REST requests for lifecycle events will not count towards your message limit. If you are making use of Reactor however, then each message sent over Reactor will count towards your message limits.

Please note that, you can use our realtime endpoint to subscribe to channel lifecycle events (such as channels being created or closed) and occupancy events (such as publishers, subscribers or presence members being added or removed) for any active channels.

In addition, note that since the metadata of various channels is prone to change very frequently, unless you have a special use case within your app, we recommend you to subscribe to the Channel Metadata API’s realtime events rather than querying this data through REST, as the data might become stale as soon as you have received it.


Metachannels are a namespace of channels which all start with the [meta] qualifier, uniquely identifying them from regular channels. An example of a metachannel would be [meta]channel.lifecycle.

There are a number of metachannels available, which are:

This metachannel is used to broadcast log messages (usually error messages) for events that occur within the application’s context
This metachannel carries messages about channel lifecycle and metadata
This metachannel carries messages about the lifecycle of realtime connections

All of the metadata associated with an app or a channel is available on one of these metachannels only.


A regular Ably key has a capability which lists available resources and, for any given resource, a set of permitted operations. The wildcard resource ‘*’ will match any regular channel name.

In order to grant permission to a user to access a metachannel, however, the resource name(s) in the capability must include the [meta] qualifier explicitly. If you are using an API Key, you can set up capabilities in your dashboard. If you are making use of tokens, you specify it within the token. The following are examples of capabilities that will validly permit access to a metachannel:


The above will allow for the key to subscribe to any meta channel. The wildcard * indicates anything can follow the [meta] claim, so an example of a valid channel would be [meta]log. However, this capability will not allow for any other actions to be performed on the metachannels, nor will it allow the key to do anything with any non-metachannels.


The above permission provides two capabilities; the ability to perform any action on any metachannel (such as [meta]log) with "[meta]*":["*"], and the ability to perform any action on any channel (such as another:channel) with "*":["*"]. However, you are never able to publish or be present in a metachannel, thus this permission in effect would result in an actual permission excluding publish and presence capabilities in [meta] channels due to the intersecting capabilities.

If [meta] is not specified in the permissions, you will be unable to access the metachannels however. An example of this would be the following:


Although the above provide all capabilities in all regular channel, without a [meta] permission being explicitily specified, you will be unable to peform any actions on a [meta] channel.

Requesting Channel Status

Through the REST library, it is possible to not only check a channel’s status and occupancy data, but it is also possible to enumerate all channels that are currently active within an app.

Channel lifecycle status

This returns a ChannelDetails for the given channel, indicating global occupancy. A side-effect of this request, in this pre-release of this API, is that it will cause the channel in question to become activated; therefore it is primarily intended to be used in conjunction with the enumeration API or in situations where the application has another means to know whether or not a given channel is active. A future version of this API will remove that restriction.

Example request:

curl<channelId> \
 -u "{{API_KEY}}"

The credentials presented with the request must include the channel-metadata permission for the channel in question.

Client libraries currently do not support this API, but it is usable via the generic request API.

It is worth noting that occupancy is currently only available to our enterprise customers. However, you can still try and test out the occupancy events using your free account.

Channel enumeration

This enumerates all active channels in the application. This is a paginated API following the same API conventions as other paginated APIs in the Ably REST library.

Example request:

curl \
 -u "{{API_KEY}}"

This will return either a list of channel names, or a ChannelDetails object depending on what options you’ve specified.

The following parameters are supported:

100 optionally specifies the maximum number of results to return. A limit greater than 1000 is unsupported
Type: integer
optionally limits the query to only those channels whose name starts with the given prefix
Type: string
value optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)

The credentials presented with the request must include the channel-metadata permission for the wildcard resource (‘*’) or, if a prefix is specified, for a resource that matches the prefix.

Client libraries currently do not provide a dedicated API to enumerate channels, but make this available using the request method. When using this, you can simply iterate through the PaginatedResults to enumerate through the results.

Enumeration is possible of all channels in an app, by repeated calls to the API, following the next relative link on each successive call, until there is no next relative link. However, the state of the app and the cluster itself can change during that enumeration. This API therefore has the following limitations:

- channels that become active, or become inactive, between the first and last request in the sequence, might or might not appear in the result. The API guarantees that if a channel is continuously active from the time that the first request is made until the time that the last request completes, then it is guaranteed to be present in the result. Similarly, if a channel is continously inactive between those times then it is guaranteed not to be present in the result
- cluster state changes, in this first release of this API, may cause a pagination sequence to become invalid, in which case the request will respond with an error with code 40011. In this case, to get a complete result, it is necessary to start the enumeration again from the beginning. Other API options to deal with this possibility will be provided in later versions of this API. Enumerations that are satisfiable in the first response page do not have this issue.

Use cases

Having access to channel metadata can provide numerous benefits. In a scenario where the number of subscribers of a channel goes well beyond a hundred, usage of other options such as presence becomes less effective leading to an unexpected n-squared problem if all of the clients are subscribed to presence. You could instead make use of our channel metadata to check the number of active subscribers.

Equally, you may want to publish your data only if there is a subscriber for that data. The channel lifecycle events can notify you when a channel is opened, becomes active, or is no longer active thus giving your publisher clients an opportunity to know when the last subscriber leaves the channel.

If you need to be able to query channel metadata at any point, you can make use of the Channel Status API to inspect the state of individual channels, or enumerate all active channels in an app.


If you wish to see an example of how to use channel metadata, you can check out our Channel Lifecycle Events tutorial, Channel Occupancy Events tutorial, and the Channel Enumeration tutorial.

Channel Status API Reference


The payload of lifecycle events for channels is the ChannelDetails type which contains the channelId and other static information about the channel, plus a status containing a ChannelStatus instance which contains information about the current state of the channel.


ChannelDetails is an object returned when requesting channel metadata. It contains information on the channel itself, along with the current state of the channel in the ChannelStatus object.

the required name of the channel including any qualifier, if any
Type: string
in events relating to the activity of a channel in a specific region, this optionally identifies the region
Type: string
in events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is resonsible for global coordination of the channel
Type: string
an optional ChannelStatus instance
Type: ChannelStatus


ChannelStatus is contained within the above ChannelDetails object, and optionally contains the below Occupancy object.

a required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity
Type: boolean
an optional Occupancy instance indicating the occupancy of the channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
Type: Occupancy


Occupancy is optionally contained within the above ChannelStatus object, and contains information on the occupants of the channel.

an optional dictionary of membership categories for a realtime channel and their counts. Membership categories include:
– publishers
the number of connections attached to the channel that are authorised to publish
Type: integer
– subscribers
the number of connections attached that are authorised to subscribe to messages
Type: integer
– presenceSubscribers
the number of connections that are authorised to subscribe to presence messages
Type: integer
– presenceConnections
the number of connections that are authorised to enter members into the presence channel
Type: integer
– presenceMembers
the number of members currently entered into the presence channel
Type: integer

Back to top