# List guests

`GET /onair.guest.list`

## Description

Returns a paginated list of guests for an On-Air event. Optionally filter by RSVP status.

Results are sorted by creation time in descending order (most recently added first).

**Access:** Organization and Personal.

**Required scope:** `onair:read`

---

**OpenAPI Spec:** [onair.json](https://developer.ro.am/onair.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `eventId` | query | string | Yes | The event identifier. |
| `status` | query | "invited" | "going" | "maybe" | "notGoing" | No | Filter by RSVP status. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |
| `limit` | query | integer | No | Maximum number of guests to return (default 100). |

## Responses

### 200 - A paginated list of guests.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `guests` | OnAirGuest[] | No |  |
| `nextCursor` | string | No | Opaque cursor to fetch the next page. Absent when there are no more results. |

**OnAirGuest** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier of the guest. |
| `eventId` | string | Yes | Identifier of the event this guest belongs to. |
| `email` | string | No | Email address of the guest. |
| `name` | string | No | Display name of the guest. |
| `phone` | string | No | Phone number of the guest. |
| `status` | "invited" | "going" | "maybe" | "notGoing" | Yes | RSVP status of the guest. |
| `created` | string | No | When the guest was added (RFC 3339). |
| `updated` | string | No | When the guest record was last updated (RFC 3339). |


#### Example Response

```json
{
  "guests": [
    {
      "id": "gst_xyz789",
      "eventId": "evt_abc123",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "status": "going",
      "created": "2026-03-15T10:00:00Z",
      "updated": "2026-03-15T12:00:00Z"
    }
  ],
  "nextCursor": "YzE6Z3N0X3h5ejc4OQ"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/onair-api/onair-guest-list*
