Channel Status API

The Channel Status API provides the capability to access information about channels via the Ably REST endpoint. The information includes the current state of a channel, or its current occupancy. 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 do not count towards your message limit. If you are making use of Integrations however, then each message sent through Integrations will count towards your message limits.

Note that it is also possible to use the realtime endpoint to subscribe to:

• Metachannels – to obtain channel and connection lifecycle metadata.
• Inband channel occupancy events – to obtain occupancy metrics such as the counts of publishers, subscribers or presence members as they are added or removed.

Note that since the metadata of various channels is prone to change very frequently, unless you have a special use case within your app, Ably recommends you subscribe to the realtime events using metchannels or inband channel occupancy rather than polling for status updates via REST, as this is inefficient and data is likely to become stale as soon as you have received it.

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.

This returns a ChannelDetails for the given channel, indicating global occupancy. A side-effect of this request, in the current version 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.

Example request:

curl https://rest.ably.io/channels/<channelId> \
 -u "<loading API key, please wait>"
API Key:
Demo Only
Copy
Copied!

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.

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.

This API is intended for occasional use by your servers only; for example, to get an initial set of active channels to be kept up to date using the channel lifecycle metachannel. It is heavily rate-limited: only a single in-flight channel enumeration call is permitted to execute at any one time. Further concurrent calls will be refused with an error with code 42912.

Example request:

curl https://rest.ably.io/channels \
 -u "<loading API key, please wait>"
API Key:
Demo Only
Copy
Copied!

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:

limit

100 optionally specifies the maximum number of results to return. A limit greater than 1000 is unsupportedType: integer

prefix

optionally limits the query to only those channels whose name starts with the given prefixType: string

by

value optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value is the default, but if you do not actually need the extra information you get with that, we strongly recommend you use by=id, which will be faster)

The credentials presented with the request must include the channel-metadata permission for the wildcard resource '*'.

Client libraries 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, this is subject to several 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 continuously inactive between those times then it is guaranteed not to be present in the result;
• Since the state of the cluster may change between successive calls, a pagination sequence may 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 maybe provided in later versions of this API. Enumerations that are satisfiable in the first response page do not have this issue.
• The API does not guarantee that the limit will be achieved even if that would be possible. For example, if you specify a limit of 100, the API may return only 37 results together with a next link to get the next page, even if you have more than 37 channels. In the extreme case, the API may return 0 results with a next link. In particular this may be the case if you have a large number of active channels but are specifying a prefix that excludes a significant proportion of them.
• The API does not guarantee that there will be no duplicated results between different pages, especially if a channel is alive in multiple regions. (It does not currently do so, but it may begin to do so with no warning or deprecation period, so your implementation should be able to cope with duplication)

Tutorials provide step-by-step documentation on how to obtain and use metadata:

• Channel Enumeration
• Channel Lifecycle Events
• Inband Channel Occupancy Events

View the Channel Status API Reference.