---
title: "List channels"
method: GET
path: "/channels"
tags: ["Channels"]
---

# List channels

`GET /channels`

## Request

- Base URL: `https://api.spectate.net/v1`
- URL: `https://api.spectate.net/v1/channels`
- Auth: HTTP bearer

Returns the team's channels, by name.

## Query parameters

- `filter[type]` 'email' | 'slack' | 'discord' | 'microsoft_teams' | 'telegram' | 'webhook' | 'pushover' | 'sms' | 'voice'
- `filter[enabled]` boolean
- `page` integer
- `per_page` integer

## Response `200`

Paginated set of `Channel`

- object
  - `current_page` integer, required
  - `data` Channel[], required
    - `id` string, uuid, required: Channel ID
    - `name` string, required: Name shown in escalation paths
    - `type` 'email' | 'slack' | 'discord' | 'microsoft_teams' | 'telegram' | 'webhook' | 'pushover' | 'sms' | 'voice', required
    - `enabled` boolean, required: Whether the channel delivers. `false` when a member turned it off or Spectate did after repeated failures (`auto_disabled`)
    - `auto_disabled` boolean, required: Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with `enable`
    - `disabled_at` string, date-time, nullable, required: When the channel was turned off automatically
    - `disabled_reason` string, nullable, required: Why it was turned off automatically
    - `consecutive_failures` integer, required: Failed deliveries since the last successful one
    - `failing_since` string, date-time, nullable, required: Since when deliveries fail
    - `last_failure_at` string, date-time, nullable, required: When a delivery last failed
    - `last_failure_reason` string, nullable, required: Why the last delivery failed
    - `last_delivered_at` string, date-time, nullable, required: When a delivery last succeeded
    - `email` ChannelEmail, required: Where an `email` channel sends.
      - `address` string, email, required: The address alerts go to
    - `slack` ChannelSlack, required: Where a `slack` channel posts: a channel of a Slack workspace connected under Integrations.
      - `installation_id` string, uuid, nullable, required: The team's Slack installation (workspace) that posts. `null` for older channels with their own bot token
      - `channel` string, required: The Slack channel ID
      - `channel_name` string, nullable, required: The channel's name, for display
    - `telegram` ChannelTelegram, required: The chat a `telegram` channel sends to. Telegram channels are connected from the dashboard (Alerting → Channels), not through the API.
      - `chat_id` string, required: The Telegram chat ID
      - `chat_title` string, nullable, required: The chat's title, for display
    - `webhook` ChannelWebhook, required: What a `webhook` channel sends. The URL and header values can hold credentials, so only the host and the header names are returned.
      - `host` string, nullable, required: The host of the URL the channel posts to
      - `header_names` string[], required: Names of the headers it sends
    - `pushover` ChannelPushover, required: Who a `pushover` channel notifies. The application token is write-only.
      - `user_key` string, required: The Pushover user or group key
      - `priority` integer, nullable, required: Pushover priority, -2 (lowest) to 2 (emergency); `null` for normal (0)
    - `sms` ChannelPhone, required: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits.
      - `phone_number` string, required: The phone number in international format
    - `voice` ChannelPhone, required: The phone an `sms` or `voice` channel reaches. Each message or call uses the team's notification credits.
      - `phone_number` string, required: The phone number in international format
    - `created_at` string, date-time, required: When the channel was created
  - `first_page_url` string, nullable, required
  - `from` integer, nullable, required
  - `last_page_url` string, nullable, required
  - `last_page` integer, required
  - `links` object[], required: Generated paginator links.
    - `url` string, nullable, required
    - `label` string, required
    - `active` boolean, required
  - `next_page_url` string, nullable, required
  - `path` string, nullable, required: Base path for paginator generated URLs.
  - `per_page` integer, required: Number of items shown per page.
  - `prev_page_url` string, nullable, required
  - `to` integer, nullable, required: Number of the last item in the slice.
  - `total` integer, required: Total number of items being paginated.

## Other responses

- `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.
- `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.
- `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.

---

[API](https://skmtc.dev/spectate/apis/spectate-api.md) - [All operations](https://skmtc.dev/spectate/apis/spectate-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spectate/apis/spectate-api/revisions/9b1a233997de?raw)