Channel Pagination

The channel query endpoint allows you to paginate messages, watchers, and members for a channel. Messages use ID-based pagination for consistency, while members and watchers use offset-based pagination.

Message Pagination

Message pagination uses ID-based parameters rather than simple offset/limit. This approach improves performance and prevents issues when the message list changes while paginating.

For example, if you fetched the first 100 messages and want to load the next 100, pass the ID of the oldest message (when paginating in descending order) or the newest message (when paginating in ascending order).

Pagination Parameters

Parameter	Description
`id_lt`	Retrieve messages older than (less than) the ID
`id_gt`	Retrieve messages newer than (greater than) the ID
`id_lte`	Retrieve messages older than or equal to the ID
`id_gte`	Retrieve messages newer than or equal to the ID
`id_around`	Retrieve messages around a specific message ID

// Get the ID of the oldest message on the current page
const lastMessageId = messages[0].id;

// Fetch older messages
const result = await channel.query({
  messages: { limit: 20, id_lt: lastMessageId },
});

// Fetch messages around a specific message
const result = await channel.query({
  messages: { limit: 20, id_around: messageId },
});

val channelClient = client.channel("messaging", "general")
val pageSize = 10

// Request the first page
val request = QueryChannelRequest()
  .withMessages(pageSize)

channelClient.query(request).enqueue { result ->
  if (result is Result.Success) {
    val messages: List<Message> = result.value.messages
    if (messages.size < pageSize) {
      // All messages loaded
    } else {
      // Load next page using the oldest message ID
      val nextRequest = QueryChannelRequest()
        .withMessages(Pagination.LESS_THAN, messages.last().id, pageSize)
      // ...
    }
  } else {
    // Handle Result.Failure
  }
}

let messageId: MessageId = "123"
let channelId = ChannelId(type: .messaging, id: "general")
let controller = chatClient.channelController(for: channelId)

// Load messages around a specific message (id_around)
controller.loadPageAroundMessageId(messageId) { error in
  if let error = error {
    print(error)
  } else {
    print(controller.messages)

    // Load newer messages (id_gt)
    controller.loadNextMessages(limit: 10) { error in
      print(error ?? controller.messages)

      // Load older messages (id_lt)
      controller.loadPreviousMessages(limit: 10) { error in
        print(error ?? controller.messages)
      }
    }
  }
}

// Alternative: Use Chat for more granular control
let chat = chatClient.makeChat(for: channelId)

// Messages newer than ID (id_gt)
let newerMessages = try await chat.loadMessages(after: messageId, limit: 10)

// Messages older than ID (id_lt)
let olderMessages = try await chat.loadMessages(before: messageId, limit: 10)

// Messages around ID (id_around)
let aroundMessages = try await chat.loadMessages(around: messageId, limit: 10)

// Channel is loaded with the most recent messages
var channel = await Client.GetOrCreateChannelWithIdAsync(ChannelType.Messaging, channelId: "my-channel-id");

// Every call will load 1 more page of messages
await channel.LoadOlderMessagesAsync();

from getstream.models import MessagePaginationParams

# Get the ID of the oldest message on the current page
last_message_id = messages[0]["id"]

# Fetch older messages
result = channel.get_or_create(
    messages=MessagePaginationParams(limit=50, id_lt=last_message_id),
)

# Fetch messages around a specific message
result = channel.get_or_create(
    messages=MessagePaginationParams(limit=20, id_around=message_id),
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Get the ID of the oldest message on the current page
last_message_id = messages[0]['id']

# Fetch older messages
result = client.chat.get_or_create_channel('messaging', 'general',
  Models::ChannelGetOrCreateRequest.new(
    messages: Models::MessagePaginationParams.new(limit: 50, id_lt: last_message_id)
  )
)

# Fetch messages around a specific message
result = client.chat.get_or_create_channel('messaging', 'general',
  Models::ChannelGetOrCreateRequest.new(
    messages: Models::MessagePaginationParams.new(limit: 50, id_around: message_id)
  )
)

use GetStream\ChatClient;
use GetStream\GeneratedModels as Models;

$response = $client->getOrCreateChannel("messaging", "general", new Models\ChannelGetOrCreateRequest(
    messages: new Models\MessagePaginationParams(limit: 20, idLt: $lastMessageId),
));

channel := client.Chat().Channel("messaging", "general")

// Fetch older messages using the oldest message ID
channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
	Messages: &getstream.MessagePaginationParams{
		Limit: getstream.PtrTo(50),
		IDLt:  getstream.PtrTo(lastMessageID),
	},
})

// Fetch messages around a specific message
channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
	Messages: &getstream.MessagePaginationParams{
		Limit:    getstream.PtrTo(20),
		IDAround: getstream.PtrTo(messageID),
	},
})

using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");
var chat = new ChatClient(client);

// Get the ID of the oldest message on the current page
var lastMessageId = messages[0].ID;

// Fetch older messages
var resp = await chat.GetOrCreateChannelAsync("messaging", "general",
    new ChannelGetOrCreateRequest
    {
        Messages = new MessagePaginationParams { Limit = 50, IDLt = lastMessageId }
    });

// Android SDK
ChannelClient channelClient = client.channel("messaging", "general");
int pageSize = 10;

// Request the first page
QueryChannelRequest request = new QueryChannelRequest()
    .withMessages(pageSize);

channelClient.query(request).enqueue(result -> {
  if (result.isSuccess()) {
    List<Message> messages = result.data().getMessages();
    if (messages.size() < pageSize) {
      // All messages loaded
    } else {
      // Load next page using the oldest message ID
      Message lastMessage = messages.get(messages.size() - 1);
      QueryChannelRequest nextRequest = new QueryChannelRequest()
          .withMessages(LESS_THAN, lastMessage.getId(), pageSize);
      // ...
    }
  } else {
    // Handle result.error()
  }
});

// Backend SDK
String lastMessageId = lastMessage.getId();
chat.getOrCreateChannel("type", "id", GetOrCreateChannelRequest.builder()
    .messages(MessagePaginationParams.builder()
        .idLt(lastMessageId)
        .build())
    .build()).execute();

Member and Watcher Pagination

Members and watchers use limit and offset parameters for pagination.

Parameter	Description	Maximum
`limit`	Number of records to return	300
`offset`	Number of records to skip	10000

// Paginate members and watchers
const result = await channel.query({
  members: { limit: 20, offset: 0 },
  watchers: { limit: 20, offset: 0 },
});

const result = await channel.query({
  state: true,
  members: { limit: 110, offset: 0 },
});

var channel = await Client.GetOrCreateChannelWithIdAsync(ChannelType.Messaging, channelId: "my-channel-id");

// channel.Members exposes the loaded members snapshot (max 100 by default)
foreach (var member in channel.Members)
{
    // ...
}

// channel.Watchers exposes the loaded watchers snapshot (max 100 by default)
foreach (var watcher in channel.Watchers)
{
    // ...
}

// Use QueryMembersAsync to page beyond the loaded snapshot
var filters = new Dictionary<string, object>();
var nextMembers = await channel.QueryMembersAsync(filters, limit: 20, offset: 0);

// Paginating watchers beyond the loaded list is not yet available in the Unity SDK.
// Please let us know if you'd like this feature implemented: https://github.com/GetStream/stream-chat-unity/issues

from getstream.models import PaginationParams

# Paginate members and watchers
result = channel.get_or_create(
    members=PaginationParams(limit=20, offset=0),
    watchers=PaginationParams(limit=20, offset=0),
)

result = channel.get_or_create(
    state=True,
    members=PaginationParams(limit=110, offset=0),
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Paginate members and watchers
result = client.chat.get_or_create_channel('messaging', 'general',
  Models::ChannelGetOrCreateRequest.new(
    members: Models::PaginationParams.new(limit: 20, offset: 0),
    watchers: Models::PaginationParams.new(limit: 20, offset: 0)
  )
)

result = client.chat.get_or_create_channel('messaging', 'general',
  Models::ChannelGetOrCreateRequest.new(
    state: true,
    members: Models::PaginationParams.new(limit: 110, offset: 0)
  )
)

use GetStream\ChatClient;
use GetStream\GeneratedModels as Models;

$response = $client->getOrCreateChannel("messaging", "general", new Models\ChannelGetOrCreateRequest(
    members: new Models\PaginationParams(limit: 20, offset: 0),
    watchers: new Models\PaginationParams(limit: 20, offset: 0),
));

channel := client.Chat().Channel("messaging", "general")

// Paginate members and watchers
channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
	Members:  &getstream.PaginationParams{Limit: getstream.PtrTo(20), Offset: getstream.PtrTo(0)},
	Watchers: &getstream.PaginationParams{Limit: getstream.PtrTo(20), Offset: getstream.PtrTo(0)},
})

// Paginate members and watchers
var resp = await chat.GetOrCreateChannelAsync("messaging", "general",
    new ChannelGetOrCreateRequest
    {
        Members = new PaginationParams { Limit = 20, Offset = 0 },
        Watchers = new PaginationParams { Limit = 20, Offset = 0 }
    });

To retrieve filtered and sorted members in a channel use the Query Members API

Querying Members

Channel Members

On this page:

Message Pagination
- Pagination Parameters
Member and Watcher Pagination