List a channel's created and shared threads

GET/v1/channels/{channelId}/threads

Requires active organization membership and threads:read scope. Includes existing threads shared through channel messages, once per thread, alongside agent threads created by mentions in this channel, newest first. Channel-created threads are omitted from ordinary thread lists; shared originals retain their location. Read their history through the canonical /threads/{threadId}/timeline and /threads/{threadId}/events endpoints.

How to call this endpoint

Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.

Path, query, and header parameters

These parameters control which ACP object the endpoint acts on and how the request is processed.

Path parameters

Name	Location	Type	Required	Description
channelId	path	string	Yes	—

Query parameters

Name	Location	Type	Required	Description
limit	query	integer	No	—
offset	query	integer	No	—

Body schema

This endpoint does not require a request body.

None.

What the API returns

Each response code below includes the documented payload shape for the ACP API.

200Agent threads and the total number of retained threadsapplication/json

Field	Type	Required	Description
data	object[]	Yes	—
data[].id	string	Yes	Unique identifier.
data[].channelId	string	Yes	—
data[].sourceEventId	string	Yes	—
data[].title	string	Yes	Display title.
data[].agentId	string	Yes	Agent ID.
data[].agentName	string	Yes	—
data[].environmentId	string	Yes	Computer ID.
data[].environmentName	string	Yes	—
data[].status	string	Yes	Queue/execution status, including queued, running, completed, failed, cancelled and permission_asked.
data[].threadStatus	string	Yes	Canonical thread status, independent of the initial mention job.
data[].batchJobId	string	Yes	—
data[].createdAt	string	Yes	ISO 8601 timestamp.
data[].updatedAt	string	Yes	ISO 8601 timestamp.
total	integer	Yes	—

400Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

401Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

403Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

404Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

500Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

503Invalid input (400), unauthenticated (401), denied (403), unavailable resource (404), stale revision/idempotency conflict/archived channel (409), unavailable PostgreSQL backend (503), or failed operation (500).application/json

Field	Type	Required	Description
error	string	Yes	—
code	string	No	—
message	string	Yes	Message text.

List a channel's created and shared threads

Response 200

See the ACP quickstart and SDK flow