---
title: "Query deleted channels"
method: POST
path: "/channels/deleted"
tags: ["product:chat"]
---

# Query deleted channels

`POST /channels/deleted`

## Request

- Base URL: `https://chat.stream-io-api.com`
- URL: `https://chat.stream-io-api.com/channels/deleted`
- Auth: one of:
  - API key in header `Authorization` and API key in query parameter `api_key` and API key in header `Stream-Auth-Type`
  - API key in query parameter `api_key` and API key in header `Stream-Auth-Type`

Lists soft-deleted channels, ordered by created_at. Server-side only. Without a filter it lists every soft-deleted channel of the app; filter by team to scope it to one tenant. To permanently remove the returned channels, pass their cids to Delete channels (POST /channels/delete) with hard_delete set to true; the single-channel Delete channel endpoint does not accept soft-deleted channels.

## Request body

- QueryDeletedChannelsRequest, nullable
  - `filter_conditions` object: Optional filter. Omit it, or pass {}, to list every soft-deleted channel of the app; for example {"team": "tenant-a"} narrows to one tenant
  - `limit` integer: Number of channels per page, 1-100 (default 25)
  - `next` string: Cursor for the next page, from the previous response
  - `prev` string: Cursor for the previous page, from the previous response
  - `sort` SortParamRequest[]: Sort order. Only created_at is supported; defaults to created_at ascending
    - `direction` integer: Direction of sorting, 1 for Ascending, -1 for Descending, default is 1. One of: -1, 1
    - `field` string: Name of field to sort by
    - `type` string: Type of field to sort by. Empty string or omitted means string type (default). One of: number, boolean

## Response `201`

Successful response

- QueryDeletedChannelsResponse, nullable
  - `channels` ChannelResponse[], required: Soft-deleted channels matching the filter, each with deleted_at set
    - `active_member_count` integer: Number of members who are not deactivated or deleted
    - `auto_translation_enabled` boolean: Whether auto translation is enabled or not
    - `auto_translation_language` string: Language (or comma-separated list of languages) to translate to when auto translation is active
    - `blocked` boolean: Whether this channel is blocked by current user or not
    - `cid` string, required: Channel CID (<type>:<id>)
    - `config` ChannelConfigWithInfo
      - `allowed_flag_reasons` string[]
      - `automod` 'disabled' | 'simple' | 'AI', required
      - `automod_behavior` 'flag' | 'block' | 'shadow_block', required
      - `automod_thresholds` Thresholds: Sets thresholds for AI moderation
        - `explicit` LabelThresholds
          - `block` number, float: Threshold for automatic message block
          - `flag` number, float: Threshold for automatic message flag
        - `spam` LabelThresholds
          - `block` number, float: Threshold for automatic message block
          - `flag` number, float: Threshold for automatic message flag
        - `toxic` LabelThresholds
          - `block` number, float: Threshold for automatic message block
          - `flag` number, float: Threshold for automatic message flag
      - `blocklist` string
      - `blocklist_behavior` 'flag' | 'block' | 'shadow_block'
      - `blocklists` BlockListOptions[]
        - `behavior` 'flag' | 'block' | 'shadow_block', required: Blocklist behavior. One of: flag, block, shadow_block
        - `blocklist` string, required: Blocklist name
      - `chat_preferences` ChatPreferences
        - `channel_mentions` string
        - `default_preference` string
        - `direct_mentions` string
        - `distinct_channel_messages` string
        - `group_mentions` string
        - `here_mentions` string
        - `role_mentions` string
        - `thread_replies` string
      - `commands` Command[], required
        - `args` string, required: Arguments help text, shown in commands auto-completion
        - `created_at` string, date-time: Date/time of creation
        - `description` string, required: Description, shown in commands auto-completion
        - `name` string, required: Unique command name
        - `set` string, required: Set name used for grouping commands
        - `updated_at` string, date-time: Date/time of the last update
      - `connect_events` boolean, required
      - `count_messages` boolean, required
      - `created_at` string, date-time, required
      - `custom_events` boolean, required
      - `delivery_events` boolean, required
      - `grants` object
      - `mark_messages_pending` boolean, required
      - `max_message_length` integer, required
      - `message_retention` string, required
      - `mutes` boolean, required
      - `name` string, required
      - `partition_size` integer
      - `partition_ttl` string, duration
      - `polls` boolean, required
      - `push_level` 'all' | 'all_mentions' | 'mentions' | 'direct_mentions' | 'none': Sets the push notification level for a channel type
      - `push_notifications` boolean, required
      - `quotes` boolean, required
      - `reactions` boolean, required
      - `read_events` boolean, required
      - `reminders` boolean, required
      - `replies` boolean, required
      - `scheduled_messages_max_lead_time_seconds` integer: How far ahead, in seconds, a message can be scheduled. Present only when scheduled messages are enabled for the app. A later scheduled_at returns error code 116 (scheduled_at_too_far), whose max_lead_time_seconds carries the same value
      - `scheduled_messages_max_per_channel` integer: Maximum number of scheduled messages (scheduled or sending) a user can have in this channel. Present only when scheduled messages are enabled for the app. Scheduling more returns error code 117 (scheduled_limit_channel)
      - `scheduled_messages_max_per_user` integer: Maximum number of scheduled messages (scheduled or sending) a user can have across all channels. Present only when scheduled messages are enabled for the app. Scheduling more returns error code 118 (scheduled_limit_user)
      - `scheduled_messages_min_lead_time_seconds` integer: Minimum time ahead, in seconds, a message is scheduled for. Present only when scheduled messages are enabled for the app. A future scheduled_at closer than this is moved later, to the first whole minute at least this far ahead; it is never rejected
      - `search` boolean, required
      - `shared_locations` boolean, required
      - `skip_last_msg_update_for_system_msgs` boolean, required
      - `typing_events` boolean, required
      - `updated_at` string, date-time, required
      - `uploads` boolean, required
      - `url_enrichment` boolean, required
      - `user_message_reminders` boolean, required
    - `cooldown` integer: Cooldown period after sending each message
    - `created_at` string, date-time, required: Date/time of creation
    - `created_by` UserResponse: User response object
      - `avg_response_time` integer
      - `ban_expires` string, date-time: Date when ban expires
      - `banned` boolean, required: Whether a user is banned or not
      - `blocked_user_ids` string[], required
      - `bypass_moderation` boolean
      - `created_at` string, date-time, required: Date/time of creation
      - `custom` object, required: Custom data for this object
      - `deactivated_at` string, date-time: Date of deactivation
      - `deleted_at` string, date-time: Date/time of deletion
      - `devices` DeviceResponse[]: List of devices user is using
        - `created_at` string, date-time, required: The date when the device was created.
        - `disabled` boolean: Whether device is disabled or not
        - `disabled_reason` string: Reason explaining why device had been disabled
        - `hardware_id` string: Stable physical device identifier used to deduplicate pushes across push providers
        - `id` string, required: The device identifier.
        - `push_provider` string, required: Push provider
        - `push_provider_name` string: Push provider name
        - `user_id` string, required: User ID
        - `voip` boolean: When true the token is for Apple VoIP push notifications
      - `id` string, required: Unique user identifier
      - `image` string
      - `invisible` boolean, required
      - `language` string, required: Preferred language of a user
      - `last_active` string, date-time: Date of last activity
      - `name` string: Optional name of user
      - `online` boolean, required: Whether a user online or not
      - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
        - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
          - `enabled` boolean
        - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
          - `enabled` boolean
        - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
          - `enabled` boolean
      - `push_notifications` PushNotificationSettingsResponse
        - `disabled` boolean
        - `disabled_until` string, date-time
      - `revoke_tokens_issued_before` string, date-time: Revocation date for tokens
      - `role` string, required: Determines the set of user permissions
      - `shadow_banned` boolean, required: Whether a user is shadow banned
      - `teams` string[], required: List of teams user is a part of
      - `teams_role` object
      - `updated_at` string, date-time, required: Date/time of the last update
    - `custom` object, required: Custom data for this object
    - `deleted_at` string, date-time: Date/time of deletion
    - `disabled` boolean, required
    - `filter_tags` string[]: List of filter tags associated with the channel
    - `fork` ChannelForkSummary: A fork of an agent channel
      - `channel_cid` string, required: CID of the fork
      - `copied_message_count` integer, required: Number of messages copied into the fork, once completed. On a failed fork, the number of messages of its history, newest first, copied before the copy failed; the fork can hold a few more
      - `created_at` string, date-time, required: Date/time of the fork
      - `failed_reason` string: Why the copy of a failed fork failed: `fork_message_id_taken` (the ID a message is copied under is held by another message; fork into another channel ID) or `message_too_large` (a source message is over a size limit of agent channels: its text, custom data or attachments)
      - `oldest_source_message_id` string: ID, in the source channel, of the oldest message a truncated fork copied. The fork holds no older source message; replies of the oldest copied messages may also have been left out
      - `source_channel_cid` string, required: CID of the channel the fork was copied from
      - `source_message_id` string, required: ID of the message of the source channel the fork was made at
      - `status` string, required: `completed` once every message is copied. `backfilling` while a background task copies the history older than the newest page; the fork is usable meanwhile, and the newest messages, which an agent reads, are normally already there. The request reads at most 1,000 source messages: when those are mostly deleted, shadowed or replies shown in the channel, it copies fewer, at least the message the fork is made at, and the task copies the rest. `failed` when the copy failed for good (see `failed_reason`): nothing more is copied, the fork keeps what it holds and is usable, and it no longer counts toward the source's fork limit
      - `task_id` string: ID of the task copying the older history of a backfilling fork
      - `truncated` boolean: True, once completed, when the source held more than 10,000 messages up to the fork point: the fork holds the newest 10,000 of them
    - `frozen` boolean, required: Whether channel is frozen or not
    - `hidden` boolean: Whether this channel is hidden by current user or not
    - `hide_messages_before` string, date-time: Date since when the message history is accessible
    - `id` string, required: Channel unique ID
    - `last_message_at` string, date-time: Date of the last message sent
    - `member_count` integer: Number of members in the channel
    - `members` ChannelMemberResponse[]: List of channel members (max 100)
      - `archived_at` string, date-time
      - `ban_expires` string, date-time: Expiration date of the ban
      - `ban_from_future_channels` boolean: Whether the member's ban also applies to channels the channel's creator will create in the future (an active future channel ban by the creator targets this member)
      - `banned` boolean, required: Whether member is banned this channel or not
      - `channel_role` string, required: Role of the member in the channel
      - `created_at` string, date-time, required: Date/time of creation
      - `custom` object, required
      - `deleted_at` string, date-time
      - `deleted_messages` string[]
      - `future_channel_ban_expires` string, date-time: Expiration date of the future channel ban; absent when the future channel ban is permanent
      - `invite_accepted_at` string, date-time: Date when invite was accepted
      - `invite_rejected_at` string, date-time: Date when invite was rejected
      - `invited` boolean: Whether member was invited or not
      - `is_moderator` boolean: Whether member is channel moderator or not
      - `notifications_muted` boolean, required
      - `pinned_at` string, date-time
      - `role` string: Permission level of the member in the channel (DEPRECATED: use channel_role instead). One of: member, moderator, admin, owner
      - `shadow_banned` boolean, required: Whether member is shadow banned in this channel or not
      - `status` string
      - `updated_at` string, date-time, required: Date/time of the last update
      - `user` UserResponse: User response object
        - `avg_response_time` integer
        - `ban_expires` string, date-time: Date when ban expires
        - `banned` boolean, required: Whether a user is banned or not
        - `blocked_user_ids` string[], required
        - `bypass_moderation` boolean
        - `created_at` string, date-time, required: Date/time of creation
        - `custom` object, required: Custom data for this object
        - `deactivated_at` string, date-time: Date of deactivation
        - `deleted_at` string, date-time: Date/time of deletion
        - `devices` DeviceResponse[]: List of devices user is using
          - `created_at` string, date-time, required: The date when the device was created.
          - `disabled` boolean: Whether device is disabled or not
          - `disabled_reason` string: Reason explaining why device had been disabled
          - `hardware_id` string: Stable physical device identifier used to deduplicate pushes across push providers
          - `id` string, required: The device identifier.
          - `push_provider` string, required: Push provider
          - `push_provider_name` string: Push provider name
          - `user_id` string, required: User ID
          - `voip` boolean: When true the token is for Apple VoIP push notifications
        - `id` string, required: Unique user identifier
        - `image` string
        - `invisible` boolean, required
        - `language` string, required: Preferred language of a user
        - `last_active` string, date-time: Date of last activity
        - `name` string: Optional name of user
        - `online` boolean, required: Whether a user online or not
        - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
          - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
            - `enabled` boolean
          - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
            - `enabled` boolean
          - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
            - `enabled` boolean
        - `push_notifications` PushNotificationSettingsResponse
          - `disabled` boolean
          - `disabled_until` string, date-time
        - `revoke_tokens_issued_before` string, date-time: Revocation date for tokens
        - `role` string, required: Determines the set of user permissions
        - `shadow_banned` boolean, required: Whether a user is shadow banned
        - `teams` string[], required: List of teams user is a part of
        - `teams_role` object
        - `updated_at` string, date-time, required: Date/time of the last update
      - `user_id` string, required
    - `message_count` integer: Number of messages in the channel
    - `mute_expires_at` string, date-time: Date of mute expiration
    - `muted` boolean: Whether this channel is muted or not
    - `own_capabilities` ChannelOwnCapability[]: List of channel capabilities of authenticated user
    - `team` string: Team the channel belongs to (multi-tenant only)
    - `truncated_at` string, date-time: Date of the latest truncation of the channel
    - `truncated_by` UserResponse: User response object
      - `avg_response_time` integer
      - `ban_expires` string, date-time: Date when ban expires
      - `banned` boolean, required: Whether a user is banned or not
      - `blocked_user_ids` string[], required
      - `bypass_moderation` boolean
      - `created_at` string, date-time, required: Date/time of creation
      - `custom` object, required: Custom data for this object
      - `deactivated_at` string, date-time: Date of deactivation
      - `deleted_at` string, date-time: Date/time of deletion
      - `devices` DeviceResponse[]: List of devices user is using
        - `created_at` string, date-time, required: The date when the device was created.
        - `disabled` boolean: Whether device is disabled or not
        - `disabled_reason` string: Reason explaining why device had been disabled
        - `hardware_id` string: Stable physical device identifier used to deduplicate pushes across push providers
        - `id` string, required: The device identifier.
        - `push_provider` string, required: Push provider
        - `push_provider_name` string: Push provider name
        - `user_id` string, required: User ID
        - `voip` boolean: When true the token is for Apple VoIP push notifications
      - `id` string, required: Unique user identifier
      - `image` string
      - `invisible` boolean, required
      - `language` string, required: Preferred language of a user
      - `last_active` string, date-time: Date of last activity
      - `name` string: Optional name of user
      - `online` boolean, required: Whether a user online or not
      - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
        - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
          - `enabled` boolean
        - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
          - `enabled` boolean
        - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
          - `enabled` boolean
      - `push_notifications` PushNotificationSettingsResponse
        - `disabled` boolean
        - `disabled_until` string, date-time
      - `revoke_tokens_issued_before` string, date-time: Revocation date for tokens
      - `role` string, required: Determines the set of user permissions
      - `shadow_banned` boolean, required: Whether a user is shadow banned
      - `teams` string[], required: List of teams user is a part of
      - `teams_role` object
      - `updated_at` string, date-time, required: Date/time of the last update
    - `type` string, required: Type of the channel
    - `updated_at` string, date-time, required: Date/time of the last update
  - `duration` string, required: Duration of the request in milliseconds
  - `next` string
  - `prev` string

## Other responses

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

## Changes

> 574 revisions in range; 3 not diffed.

- **2026-10-30** `00df5052235b`: 1 info
  - added the optional property `channels/items/fork/failed_reason` to the response with the `201` status
- **2026-10-29** `8acf79c23a74`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getstream/apis/stream-api/changes/channels/deleted/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.dev/getstream/apis/stream-api/revisions/1fda44d40b27?raw)