# List magicasts

`GET /magicast.list`

## Description

List Magicasts in your account, most recent first.

Returns metadata only (`id`, `name`, `createdAt`, `ownerId`,
`coverImageUrl`). Use [`/magicast.info`](/docs/api/magicast-info) for
transcript cues, chapters, video status, and a signed download URL.

**Access:** Organization and Personal. Organization tokens list every
Magicast in the account, including ones the creator never shared. Personal
tokens are restricted to Magicasts owned by the authenticated user.

**Required scope:** `magicast:read`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `after` | query | string | No | Only return magicasts created after this time (RFC-3339). |
| `before` | query | string | No | Only return magicasts created before this time (RFC-3339). |
| `ascending` | query | boolean | No | Sort oldest-first instead of newest-first. |
| `limit` | query | integer | No | Number of magicasts to return per response. Default 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - Magicasts retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `magicasts` | Magicast[] | No |  |
| `nextCursor` | string | No | Cursor for the next page; omitted on the last page. |

**Magicast** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier for the magicast |
| `name` | string | Yes | Display name of the magicast |
| `createdAt` | string | Yes | ISO-8601 timestamp when the magicast was created (UTC) |
| `ownerId` | string | No | Address ID of the magicast owner |
| `coverImageUrl` | string | No | URL for the magicast cover image thumbnail |


#### Example Response

```json
{
  "magicasts": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Q1 All-Hands Recap",
      "createdAt": "2026-01-21T18:30:00Z",
      "ownerId": "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
      "coverImageUrl": "https://ro.am/card-images/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "nextCursor": "YzE6MjAyNi0wMS0yMVQxODozMDowMFo6YTFiMmMzZDQtZTVmNg"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

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