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());

import os, requests

# All messages on the session.
url = f"https://api.blocks.team/rest/v1/sessions/{session_id}/messages"

# Or scope to a specific thread:
# url = f"https://api.blocks.team/rest/v1/sessions/{session_id}/threads/{thread_id}/messages"

page = requests.get(
    url,
    headers={"Authorization": f"ApiKey {os.environ['BLOCKS_API_KEY']}"},
    params={"type": "final_message", "role": "assistant"},
).json()

# All messages on the session.
curl "https://api.blocks.team/rest/v1/sessions/$SESSION_ID/messages?type=final_message&role=assistant" \
  -H "Authorization: ApiKey $BLOCKS_API_KEY"

# Or scope to a specific thread:
curl "https://api.blocks.team/rest/v1/sessions/$SESSION_ID/threads/$THREAD_ID/messages?type=final_message&role=assistant" \
  -H "Authorization: ApiKey $BLOCKS_API_KEY"

import java.net.URI;
import java.net.http.*;

String url = "https://api.blocks.team/rest/v1/sessions/" + sessionId
    + "/messages?type=final_message&role=assistant";

// Or scope to a specific thread:
// String url = "https://api.blocks.team/rest/v1/sessions/" + sessionId
//     + "/threads/" + threadId + "/messages?type=final_message&role=assistant";

HttpResponse<String> res = HttpClient.newHttpClient().send(
    HttpRequest.newBuilder(URI.create(url))
        .header("Authorization", "ApiKey " + System.getenv("BLOCKS_API_KEY"))
        .build(),
    HttpResponse.BodyHandlers.ofString());

require "net/http"
require "json"

# All messages on the session.
url = "https://api.blocks.team/rest/v1/sessions/#{session_id}/messages?type=final_message&role=assistant"

# Or scope to a specific thread:
# url = "https://api.blocks.team/rest/v1/sessions/#{session_id}/threads/#{thread_id}/messages?type=final_message&role=assistant"

page = JSON.parse(Net::HTTP.get(URI(url), {
  "Authorization" => "ApiKey #{ENV['BLOCKS_API_KEY']}",
}))

url := "https://api.blocks.team/rest/v1/sessions/" + sessionID +
    "/messages?type=final_message&role=assistant"

// Or scope to a specific thread:
// url := "https://api.blocks.team/rest/v1/sessions/" + sessionID +
//     "/threads/" + threadID + "/messages?type=final_message&role=assistant"

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("Authorization", "ApiKey "+os.Getenv("BLOCKS_API_KEY"))
res, _ := http.DefaultClient.Do(req)

​
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.