> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.awork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server.

# Lists agent thread messages.

GET https://api.awork.com/api/v1/agents/threads/{threadId}/messages

Lists messages from the specified personal-agent or custom-agent conversation.
Use this endpoint to retrieve replies after creating a thread or submitting a message.
Returns not found if the thread is missing or the user cannot read it.Any authenticated user.

Reference: https://developers.awork.com/apiv1/agent-threads/get-agents-threads-messages-by-thread-id

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `threadId` (string, required) — The thread id.

## Response

### 200

OK

- `list of AgentThreadMessageResponseModel`

## Errors

### 404 Not Found Error

Not Found

- `code` (string, required) — The error code.
- `description` (string, required) — The description of the error.
- `link` (string, required) — The link to the API documentation page.
- `details` (list of string, optional, nullable) — A list of details describing the error.
- `validationErrors` (list of ValidationErrorResponse, optional, nullable) — If a validation error occurred, this contains the validation errors for each property.
- `traceId` (string, optional, nullable) — The request trace id for tracking the request.

## Types

### AgentThreadMessageResponseModel

Describes a message in an agent thread.

- `id` (string, optional) — The id of the entity.
- `createdOn` (string, optional) — The date this entity was created.
- `createdBy` (string, optional) — The id of the user who created this entity.
- `updatedOn` (string, optional) — The date this entity was last modified.
- `updatedBy` (string, optional) — The id of the user who last modified this entity.
- `threadId` (string, optional) — The thread that owns the message.
- `parentThreadId` (string, optional, nullable) — The parent thread for a delegated message.
- `role` (string, optional, nullable) — The message author's role.
- `content` (string, optional, nullable) — The user-visible message text.
- `clientMessageId` (string, optional, nullable) — The client-generated idempotency key for a user message.
- `runtimeMessageId` (string, optional, nullable) — The stable message reference used by the runtime provider.
- `model` (string, optional, nullable) — The model that produced the message.
- `toolCallId` (string, optional, nullable) — The provider tool-call identifier associated with the message.
- `temporaryFiles` (list of TemporaryFileReference, optional, nullable) — The temporary files attached to the message.
- `toolCalls` (list of AiToolCall, optional, nullable) — The tool calls stored with this message.
- `reasoning` (list of AgentThreadReasoningResponseModel, optional, nullable) — The user-visible reasoning text stored with this message.
- `agentId` (string, optional, nullable) — The custom agent that produced the message, if applicable.
- `messageOrder` (integer, optional) — The message order.
- `isStreaming` (boolean, optional) — Whether the message is still streaming.
- `streamCompleted` (boolean, optional) — The stream completed.
- `traceId` (string, optional, nullable) — The distributed trace that produced the message.
- `modelProvider` (string, optional, nullable) — The model provider selected for this message.
- `reasoningLevel` (string, optional, nullable) — The reasoning level selected for this message.
- `toolAccess` (AgentToolAccessPolicy, optional) — Describes the tool access used for an agent message.
- `connectorIds` (list of string, optional, nullable) — The connector identifiers selected for this message.
- `skillIds` (list of string, optional, nullable) — The skill identifiers selected for this message.

### ValidationErrorResponse

The validation error response.

- `property` (string, optional, nullable) — The name of the property that failed validation.
- `message` (string, optional, nullable) — The reason why this property failed validation.

### TemporaryFileReference

Describes a temporary file attached to an agent message.

- `id` (string, optional, nullable) — The resource id.
- `name` (string, optional, nullable) — The display name.
- `mimeType` (string, optional, nullable) — The file media type.
- `sandboxPath` (string, optional, nullable) — The canonical sandbox path assigned after file promotion.
- `downloadUrl` (string, optional, nullable) — The relative file download URL.

### AiToolCall

Describes a tool call stored with an agent message.

- `id` (string, optional, nullable) — The provider tool call identifier.
- `toolName` (string, optional, nullable) — The runtime tool that was called.
- `connectorId` (string, optional, nullable) — The connector that supplied the tool, if applicable.
- `connectionId` (string, optional, nullable) — The connector connection used by the tool, if applicable.
- `arguments` (map from string to any, optional, nullable) — The structured arguments supplied to the tool.
- `response` (string, optional, nullable) — The serialized tool result.
- `chartBlock` (string, optional, nullable) — The serialized native chart block produced by code mode, when present.

### AgentThreadReasoningResponseModel

Represents user-visible reasoning text restored from a canonical chat payload.

- `id` (string, optional, nullable) — The provider reasoning item id.
- `text` (string, optional, nullable) — The safe reasoning summary text.

### AgentToolAccessPolicy

Describes the tool access used for an agent message.

- `webSearchEnabled` (boolean, optional) — Whether web search was enabled.
- `aworkAccessEnabled` (boolean, optional) — Whether awork access was enabled.
- `googleGenAiAccessEnabled` (boolean, optional) — Whether Google image generation was enabled.
- `openAiImageGenerationAccessEnabled` (boolean, optional) — Whether OpenAI image generation was enabled.

## Examples

**Response**

```json
[
  {
    "id": "23e68187-91d6-4f7e-8d31-e3f2c60d7427",
    "createdOn": "2022-03-11T15:33:47.100Z",
    "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8",
    "updatedOn": "2022-03-11T21:15:00.100Z",
    "updatedBy": "3d844c62-7410-4df9-a5b2-78805c0ee260",
    "threadId": "6cbb219e-839d-4d23-b273-3a78bbd842ae",
    "parentThreadId": "b5a57e4d-0eec-45b6-b55e-4b70bf0f2a18",
    "role": "agent",
    "content": "The Acme website project is on track for Friday, with budget approval still pending.",
    "clientMessageId": "client-status-2026-08-29",
    "runtimeMessageId": "msg_01K4CLIENTSTATUS",
    "model": "gpt-5.6-terra",
    "toolCallId": "call_01K4CLIENTSTATUS",
    "temporaryFiles": [
      {
        "id": "temp_01K4CLIENTBRIEF",
        "name": "acme-client-brief.pdf",
        "mimeType": "application/pdf",
        "sandboxPath": "context/uploads/awork-9ad6397243964b0b9e7d40b852cdebf8-acme-client-brief.pdf",
        "downloadUrl": "/api/v1/agents/threads/6cbb219e-839d-4d23-b273-3a78bbd842ae/artifacts/download?path=client-status-report.pdf"
      }
    ],
    "toolCalls": [
      {
        "id": "call_01K4CLIENTSTATUS",
        "toolName": "code_mode_execute",
        "connectorId": "7e376777-7834-4af6-9eb8-da065f568d30",
        "connectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c",
        "arguments": {},
        "response": "{\"status\":\"completed\"}",
        "chartBlock": "{\"type\":\"chart\",\"version\":1,\"spec\":{\"style\":\"bar\",\"series\":[{\"name\":\"Revenue\",\"values\":[1,2]}]}}"
      }
    ],
    "reasoning": [
      {
        "id": "reasoning_01J8M7Q2A3B4C5D6E7F8G9H0JK",
        "text": "Checked the project context before preparing the answer."
      }
    ],
    "agentId": "4d22e163-2b4a-4d47-b51c-5b2217f84f57",
    "messageOrder": 2,
    "isStreaming": false,
    "streamCompleted": true,
    "traceId": "0af7651916cd43dd8448eb211c80319c",
    "modelProvider": "openai",
    "reasoningLevel": "medium",
    "toolAccess": {
      "webSearchEnabled": true,
      "aworkAccessEnabled": true,
      "googleGenAiAccessEnabled": false,
      "openAiImageGenerationAccessEnabled": false
    },
    "connectorIds": [
      "string"
    ],
    "skillIds": [
      "string"
    ]
  }
]
```

**SDK Code**

```python
import requests

url = "https://api.awork.com/api/v1/agents/threads/threadId/messages"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.awork.com/api/v1/agents/threads/threadId/messages';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.awork.com/api/v1/agents/threads/threadId/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.awork.com/api/v1/agents/threads/threadId/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.awork.com/api/v1/agents/threads/threadId/messages")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.awork.com/api/v1/agents/threads/threadId/messages', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.awork.com/api/v1/agents/threads/threadId/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.awork.com/api/v1/agents/threads/threadId/messages")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```