---
title: "Grouped query channels"
method: POST
path: "/channels/grouped"
tags: ["product:chat"]
---

# Grouped query channels

`POST /channels/grouped`

Query channels grouped into predefined buckets. Only available for enterprise apps.

## Request body

- GroupedQueryChannelsRequest, nullable
  - `groups` object — Groups to return, keyed by group name. Each group can define limit, next, or prev. 'next' and 'prev' cursors are only allowed when the request contains exactly one group; multi-group pagination is rejected.
  - `limit` integer — Default max channels per group (default 10)
  - `user` UserRequest — User request object
    - `custom` object — Custom user data
    - `id` string, required — User ID
    - `image` string — User's profile image URL
    - `invisible` boolean
    - `language` string
    - `name` string — Optional name of user
    - `privacy_settings` PrivacySettingsResponse
      - `delivery_receipts` DeliveryReceiptsResponse
        - `enabled` boolean
      - `read_receipts` ReadReceiptsResponse
        - `enabled` boolean
      - `typing_indicators` TypingIndicatorsResponse
        - `enabled` boolean
    - `role` string — User's global role
    - `teams` string[] — List of teams the user belongs to
    - `teams_role` object — Map of team-specific roles for the user
  - `user_id` string

## Response `201`

Grouped Query Channels Response

- GroupedQueryChannelsResponse, nullable
  - `duration` string, required — Duration of the request in milliseconds
  - `groups` object, required — Predefined channel groups keyed by group name

## Other responses

- `400` — Bad request
- `429` — Too many requests

## Changes

> 88 revisions in range; 2 not diffed.

- **2026-08-12** `bb4f84a3469c` — 12 breaking
  - the `groups/additionalProperties/channels/items/active_live_locations/items/latitude` response's property type/format changed from `number`/`float` to `number`/`double` for status `201`
  - the `groups/additionalProperties/channels/items/active_live_locations/items/longitude` response's property type/format changed from `number`/`float` to `number`/`double` for status `201`
  - the `groups/additionalProperties/channels/items/messages/items/shared_location/latitude` response's property type/format changed from `number`/`float` to `number`/`double` for status `201`
  - the `groups/additionalProperties/channels/items/messages/items/shared_location/longitude` response's property type/format changed from `number`/`float` to `number`/`double` for status `201`
  - …8 more
- **2026-08-10** `6b4870a97ab0` — 1 breaking
  - removed the required property `groups/additionalProperties/channels/items/threads/items/thread_participants/items/app_pk` from the response with the `201` status
- **2026-08-05** `0e99f00bcf93` — 1 info
  - the response property `groups/additionalProperties/channels/items/threads/items/reply_count` became required for the status `201`
- …earlier changes not shown

[Full history](https://skmtc.dev/getstream/apis/stream-api/changes/channels/grouped/post.md)

---

[API](https://skmtc.dev/getstream/apis/stream-api.md) · [All operations](https://skmtc.dev/getstream/apis/stream-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getstream/stream-api/revisions/dbddf72cc34e/schema)