threads_get

List the threads in a forum channel. Use it to show a forum’s thread list, and to page through older threads as the user scrolls.

Unlike the recent-thread list inside channels_get, this list is not filtered by participation or age. See threads and forums.

Request

First page:

{
  "cmd": "threads_get",
  "channel": "projects",
  "limit": 25
}

Next page, using next_cursor from the previous response:

{
  "cmd": "threads_get",
  "channel": "projects",
  "limit": 25,
  "cursor": "eyJhY3Rpdml0eSI6MTc4ODYzMTIwMCwiaWQiOiIwYjdkMWMyZS00ZjNhLTRlOGItOWE2MS01YzJkN2U5ZjFhMzQiLCJwaW5uZWQiOmZhbHNlfQ=="
}

Threads around a known thread:

{
  "cmd": "threads_get",
  "channel": "projects",
  "around": "0b7d1c2e-4f3a-4e8b-9a61-5c2d7e9f1a34",
  "bounds": { "above": 5, "below": 5 }
}

Field	Type	Required	Description
`channel`	string	Yes	Name of the forum channel.
`limit`	integer	No	Threads per page, 1 to 100. Default `25`. Ignored when you send `around`.
`cursor`	string	No	The `next_cursor` from the previous page. Leave it out for the first page.
`around`	string	No	A thread ID. Returns that thread with its neighbours on both sides. Can’t be combined with `cursor`.
`bounds.above`	integer	No	With `around`: how many threads before it to include, 0 to 100. Default `12`.
`bounds.below`	integer	No	With `around`: how many threads after it to include, 0 to 100. Default `12`.

Threads are sorted with pinned threads first, then by latest activity, newest first. Activity is the time of the thread’s last message, or its creation time if it has no messages.

Response

{
  "cmd": "threads_get",
  "channel": "projects",
  "val": [
    {
      "id": "0b7d1c2e-4f3a-4e8b-9a61-5c2d7e9f1a34",
      "name": "My first project",
      "parent_channel": "projects",
      "created_by": "alice",
      "created_at": 1788624000,
      "locked": false,
      "archived": false,
      "participants": ["alice", "bob"],
      "message_count": 14,
      "last_message": 1788631200,
      "last_message_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10"
    }
  ],
  "cursor": "",
  "around": "",
  "has_more": true,
  "at_start": true,
  "at_end": false,
  "next_cursor": "eyJhY3Rpdml0eSI6MTc4ODYzMTIwMCwiaWQiOiIwYjdkMWMyZS00ZjNhLTRlOGItOWE2MS01YzJkN2U5ZjFhMzQiLCJwaW5uZWQiOmZhbHNlfQ=="
}

Field	Description
`val`	The page of thread objects, in sort order.
`cursor`, `around`	Echo the values you sent, or `""`.
`has_more`	`true` if more threads follow this page. Always the opposite of `at_end`.
`at_start`	`true` if the page starts at the top of the list.
`at_end`	`true` if the page reaches the bottom of the list.
`next_cursor`	Send this as `cursor` to get the next page. Present only when more threads follow.

Treat cursors as opaque strings. A cursor marks a position in the sort order, so threads created after you fetched page one don’t shift later pages.

This response goes to the caller only.

Permissions

You need to be able to view the forum. Every thread in a forum you can view is listed.

Errors

`val`	When
`Channel not found`	The channel doesn’t exist or you can’t view it.
`Threads can only be listed in forum channels`	The channel is not a forum.
`cursor and around cannot be used together`	You sent both `cursor` and `around`.
`Invalid thread cursor`	`cursor` is not a cursor the server issued.
`Thread not found`	The `around` thread is not in this forum.
Validation message	A field has the wrong type or is out of range, for example `limit: Expected at most 100`. `bounds` accepts only `above` and `below`.

threads_get

Request

Response

Permissions

Errors

See also