Skip to main content
Two endpoints share the same paginated response shape and query parameters. Use the first to list every message in a session; use the second to scope to a single thread (for example, to poll the latest follow-up’s reply). 
GET /rest/v1/sessions/{session_id}/messages
GET /rest/v1/sessions/{session_id}/threads/{thread_id}/messages
Results are sorted by created_at (newest first by default). Soft-deleted messages are excluded.

​
Request

// All messages on the session.
const url = `https://api.blocks.team/rest/v1/sessions/${sessionId}/messages?type=final_message&role=assistant`;

// Or scope to a specific thread:
// const url = `https://api.blocks.team/rest/v1/sessions/${sessionId}/threads/${threadId}/messages?type=final_message&role=assistant`;

const page = await fetch(url, {
  headers: { Authorization: `ApiKey ${process.env.BLOCKS_API_KEY}` },
}).then((r) => r.json());

​
Path parameters

​
session_id
string (uuid)
required
The session ID. Required for both URL forms.
​
thread_id
string (uuid)
required
The thread ID. Required only on the threaded URL form. The thread must belong to session_id.

​
Query parameters

​
type
string[]
default:"[\"message\", \"final_message\"]"
Repeat to combine. Allowed values: message, final_message, tool_call. Pass type=final_message to fetch only completed assistant replies.
​
role
string
default:"assistant"
Filter by sender. One of user, assistant.
​
thread_id
string (uuid)
Filter to a single thread without using the threaded URL form. Ignored on the threaded URL.
​
gts
number
Cursor for incremental polling, in epoch seconds. Returns only messages whose ts is strictly greater than this value. Use _links.new_messages.href from the previous page to get a pre-built URL with this cursor already set.
​
page
number
default:"1"
1-indexed page number. Minimum 1.
​
limit
number
default:"50"
Page size. Minimum 1, maximum 100.
​
direction
string
default:"desc"
Sort direction. One of asc, desc.

​
Response

{
  "items": [
    {
      "id": "5e1b…",
      "chat_id": "a196cec6-49cb-4c48-8e4c-2707fb5d6709",
      "chat_thread_id": "71562cd0-1f63-41b2-8382-10f2fdb1ac8b",
      "task_id": "0e7d…",
      "role": "assistant",
      "type": "final_message",
      "message": "Hi! Octopuses have three hearts — two pump blood to the gills and one to the rest of the body.",
      "ts": 1746038518,
      "created_at": "2026-04-30T18:21:42.000Z",
      "updated_at": "2026-04-30T18:21:42.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "total_pages": 1 },
  "_links": {
    "self": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/messages?type=final_message&role=assistant" },
    "new_messages": { "href": "https://api.blocks.team/rest/v1/sessions/a196cec6-…/messages?type=final_message&role=assistant&gts=1746038518" }
  }
}
​
items
object[]
Page of messages.
​
meta
object
Pagination metadata.
​
_links
object
HATEOAS links for the page.

​
Polling tips

  • For the assistant’s first reply, use the _links.final_message.href returned from Create Session — it already has the right filters applied.
  • For incremental polling, use _links.new_messages.href from the previous response. It encodes the gts cursor so each poll only returns new messages.

​
Errors

StatusCodeReason
404NOT_FOUNDSession (or thread) does not exist or belongs to a different workspace.