---
title: "List Conferences"
method: GET
path: "/conferences"
tags: ["Conferences"]
---

# List Conferences

`GET /conferences`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/conferences`
- Auth: API key in header `PINNACLE-API-KEY`

Your team's conferences, newest first, each with its participants.

## Query parameters

- `limit` integer
- `status` 'waiting' | 'active' | 'ended': - `waiting`: Created, but nobody has joined yet. - `active`: At least one participant has joined. - `ended`: Over. Every participant's call has been hung up.

## Response `200`

Conferences.

- ListConferencesResponse
  - `data` Conference[], required
    - `id` string, required
    - `label` string, nullable, required
    - `status` 'waiting' | 'active' | 'ended', required: - `waiting`: Created, but nobody has joined yet. - `active`: At least one participant has joined. - `ended`: Over. Every participant's call has been hung up.
    - `participant_count` integer, required: Participants currently joined.
    - `max_participants` integer, required
    - `hold_audio_url` string, nullable, required: What participants on hold hear.
    - `speaking_events` boolean, required: Whether `participant.speaking` events are sent when the active speaker changes.
    - `metadata` object, required
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable, required
    - `ended_at` string, date-time, nullable, required
    - `ended_reason` 'empty' | 'ended_by_api' | 'participant_ended_it' | 'time_limit' | 'expired_waiting' | 'failed', required: Why a conference ended. A conference never ends just because one person is left. - `empty`: The last participant left. - `ended_by_api`: Ended with `DELETE /conferences/{id}` or the `conference.end` command. - `participant_ended_it`: A participant added with `end_conference_on_leave: true` left. - `time_limit`: Reached the 4-hour limit. - `expired_waiting`: Nobody joined in time. - `failed`: The conference couldn't be started.
    - `participants` Participant[], required
      - `call_id` string, required: The participant is this call; every call API works on it.
      - `conference_id` string, required
      - `label` string, nullable, required
      - `status` 'dialing' | 'ringing' | 'joined' | 'left' | 'failed', required: - `dialing`: A dialed participant whose call hasn't answered yet. - `ringing`: Answered and being connected (or hearing its `announce`). - `joined`: In the conference. - `left`: Hung up or was removed. - `failed`: Never connected (busy, no answer, rejected, or an error).
      - `from` string, nullable, required
      - `to` string, nullable, required
      - `muted` boolean, required: Nobody hears this participant; they still hear everyone.
      - `on_hold` boolean, required: They hear hold audio and nobody hears them.
      - `whisper_to` string[], nullable, required: Call IDs of the only participants who can hear this one, or `null` for everyone.
      - `end_conference_on_leave` boolean, required: When this participant leaves, the conference ends for everyone.
      - `joined_at` string, date-time, nullable, required
      - `left_at` string, date-time, nullable, required
      - `left_reason` 'hangup' | 'removed' | 'busy' | 'no_answer' | 'rejected' | 'failed' | 'conference_ended', required

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)