# List ticker posts

`GET /ticker.list`

## Description

List the posts on the ticker, the strip that scrolls announcements, goals,
and wins across the Roam. The list includes posts members created in the
Roam app and posts integrations created through the API; compare each
post's `authorId` with `user.id` from [`token.info`](/docs/api/token-info)
to find your own.

Posts are returned in display order: the order people arranged them in the
Roam app, not the order they were created. The ticker holds at most 50
posts, so every post comes back in one response; there is no pagination.

No webhooks fire when posts change. Call this endpoint to see the current
posts.

Admins can turn the ticker off in Roam Administration (the "Ticker"
setting). While it is off, this call still succeeds, with `enabled: false`
and an empty `messages` list. Turning the ticker off permanently deletes
every post, and it starts empty when turned back on, so post IDs you saved
no longer exist.

**Access:** Organization only (API Key or OAuth with admin consent).
Personal tokens, including Personal Access Tokens, get `403`
`access_mode_not_supported`.

**Required scope:** `ticker:read`

---

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

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Responses

### 200 - Ticker posts retrieved successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ok` | "true" | Yes | Always `true` on success. See [Responses and Errors](/docs/guides/responses-and-errors). |
| `enabled` | boolean | Yes | Whether the ticker is turned on in this Roam. When `false`, `messages` is empty. |
| `messages` | TickerMessage[] | Yes | Every post on the ticker, in display order. |

**TickerMessage** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Post ID. |
| `category` | string | Yes | Lowercase label shown with the post, such as `announcement`, `goal`, or `news`. |
| `text` | string | Yes | Post text, as plain text. |
| `url` | string | No | HTTP(S) link the post opens. Omitted when the post has no link. |
| `authorId` | string | Yes | Who created the post: the member's user ID (resolve it with `user.info`) for a post created in the Roam app, or the integration's bot ID for a post created through the API. To find your own posts, com |
| `createdAt` | string | Yes | When the post was created (RFC-3339, UTC). |


#### Example Response

```json
{
  "ok": true,
  "enabled": true,
  "messages": [
    {
      "id": "019a0000-0000-7000-8000-0000000000a1",
      "category": "goal",
      "text": "Close 40 new accounts this quarter",
      "authorId": "709b8a57-70bc-427a-b6f0-b16ba5297f8c",
      "createdAt": "2026-01-20T15:00:00.412Z"
    },
    {
      "id": "019a0000-0000-7000-8000-0000000000a2",
      "category": "announcement",
      "text": "v4.2 is live for every customer",
      "url": "https://example.com/changelog/4-2",
      "authorId": "b893c426-6d54-4d9a-8e71-6bd53b26124e",
      "createdAt": "2026-01-21T18:30:00.127Z"
    }
  ]
}
```

### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Personal token (`access_mode_not_supported`)
- Token is missing `ticker:read` (`missing_scope`)
- The ticker is not available in this Roam (`ticker_not_available`)


### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

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