Get Session Messages

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

string (uuid)

required

The session ID. Required for both URL forms.

string (uuid)

required

The thread ID. Required only on the threaded URL form. The thread must belong to session_id.

Query parameters

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.

string

default:"assistant"

Filter by sender. One of user, assistant.

string (uuid)

Filter to a single thread without using the threaded URL form. Ignored on the threaded URL.

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.

number

default:"1"

1-indexed page number. Minimum 1.

number

default:"50"

Page size. Minimum 1, maximum 100.

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" }
  }
}

object[]

Page of messages.

Show message properties

string (uuid)

Message ID.

string (uuid)

The session this message belongs to.

string (uuid) | null

The thread the message was sent on, if any.

string (uuid)

The task ID for the agent invocation that produced this message.

string

Sender role: user or assistant.

string

Message type: message, final_message, or tool_call.

string

The message body.

number | null

Provider-supplied timestamp in epoch seconds. Use as the gts cursor for incremental polling.

string (ISO 8601)

When the message was created.

string (ISO 8601)

When the message was last updated.

object

Pagination metadata.

Show properties

number

Total messages matching the filter.

number

The current 1-indexed page.

number

The page size used for this response.

number

Total page count for the current filter.

object

HATEOAS links for the page.

Show properties

object

Link to the current page (preserves all query parameters).

object

Pre-built URL with ?gts=<cursor> appended. Poll this URL to receive only messages newer than the latest one in this page. Always present — when items is empty, the cursor is the server’s current epoch second, so the next poll returns anything created after now.

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

Status	Code	Reason
`404`	`NOT_FOUND`	Session (or thread) does not exist or belongs to a different workspace.

Get Started

Agent Sessions

Use Cases

Request

Path parameters

Query parameters

Response

Polling tips

Errors

​Request

​Path parameters

​Query parameters

​Response

​Polling tips

​Errors

Request

Path parameters

Query parameters

Response

Polling tips

Errors