Developers

Search threads

POST/v1/threads/search

Search conversation threads by text, status, and computer scope.

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
None.
Query parameters
None.

Body schema

Content type: application/json · Required

FieldTypeRequiredDescription
querystringYes—
environmentIdstringNoComputer ID.
statusactive | completed | failed | allNoCurrent lifecycle status.
limitintegerNo—
offsetintegerNo—
includeMessagesbooleanNo—

What the API returns

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

200Thread search resultsapplication/json
FieldTypeRequiredDescription
objectstringNo—
resultsobject[]No—
results[].threadobjectNo—
results[].thread.idstringNoUnique identifier.
results[].thread.userIdstringNoUser ID.
results[].thread.organizationIdstringNo—
results[].thread.createdByUserIdstringNo—
results[].thread.projectIdstringNoProject ID.
results[].thread.environmentIdstringNoComputer ID.
results[].thread.agentIdstringNoAgent ID.
results[].thread.titlestringNoDisplay title.
results[].thread.taskstringNo—
results[].thread.appIdstringNo—
results[].thread.statusactive | running | permission_asked | completed | failed | archived | cancelled | deletedNoCurrent lifecycle status.
results[].thread.contextIdstringNo—
results[].thread.contextNamestringNo—
results[].thread.messageCountintegerNo—
results[].thread.lastMessageAtstringNo—
results[].thread.lastMessagePreviewstringNo—
results[].thread.inputTokensintegerNo—
results[].thread.outputTokensintegerNo—
results[].thread.cacheTokensintegerNo—
results[].thread.totalTokensintegerNo—
results[].thread.agentCostnumberNo—
results[].thread.agentCostUsdnumberNo—
results[].thread.environmentCostnumberNo—
results[].thread.environmentCostUsdnumberNo—
results[].thread.totalCostnumberNo—
results[].thread.totalCostUsdnumberNo—
results[].thread.agentCTintegerNo—
results[].thread.environmentCTintegerNo—
results[].thread.totalCTintegerNo—
results[].thread.environmentMinutesnumberNo—
results[].thread.environmentStorageGBnumberNo—
results[].thread.attachmentsobject[]No—
results[].thread.metadataobjectNoFree-form metadata object.
results[].thread.teamExecutionobjectNo—
results[].thread.teamExecution.modeteamNo—
results[].thread.teamExecution.teamAgentIdstringNo—
results[].thread.teamExecution.teamAgentNamestringNo—
results[].thread.teamExecution.orchestratorobjectNo—
results[].thread.teamExecution.orchestrator.agentIdstringNoAgent ID.
results[].thread.teamExecution.orchestrator.agentNamestringNo—
results[].thread.teamExecution.orchestrator.claudeAgentNamestringNo—
results[].thread.teamExecution.subagentsobject[]No—
results[].thread.teamExecution.subagents[].agentIdstringNoAgent ID.
results[].thread.teamExecution.subagents[].agentNamestringNo—
results[].thread.teamExecution.subagents[].claudeAgentNamestringNo—
results[].thread.subagentActivityobject[]No—
results[].thread.subagentActivity[].agentIdstringNoAgent ID.
results[].thread.subagentActivity[].agentNamestringNo—
results[].thread.subagentActivity[].claudeAgentNamestringNo—
results[].thread.subagentActivity[].eventCountintegerNo—
results[].thread.subagentActivity[].lastActiveAtstringNo—
results[].thread.subagentActivity[].teamAgentIdstringNo—
results[].thread.subagentActivity[].teamAgentNamestringNo—
results[].thread.environmentNamestringNo—
results[].thread.agentNamestringNo—
results[].thread.agentPhotoUrlstringNo—
results[].thread.agentAvatarUrlstringNo—
results[].thread.startedAtstringNoISO 8601 timestamp.
results[].thread.completedAtstringNoISO 8601 timestamp.
results[].thread.durationstringNo—
results[].thread.queuedInBatchbooleanNo—
results[].thread.batchJobIdstringNo—
results[].thread.admissionReasonstringNo—
results[].thread.createdAtstringNoISO 8601 timestamp.
results[].thread.updatedAtstringNoISO 8601 timestamp.
results[].scorenumberNo—
results[].highlightsstring[]No—
results[].matchingMessagesobject[]No—
results[].matchingMessages[].idstringNoUnique identifier.
results[].matchingMessages[].threadIdstringNoThread ID.
results[].matchingMessages[].rolesystem | user | assistant | execution_logNo—
results[].matchingMessages[].contentstringNoRaw text content.
results[].matchingMessages[].inputTokensintegerNo—
results[].matchingMessages[].outputTokensintegerNo—
results[].matchingMessages[].durationMsintegerNo—
results[].matchingMessages[].actionsCountintegerNo—
results[].matchingMessages[].logTypestringNo—
results[].matchingMessages[].logLevelinfo | warn | error | success | warningNo—
results[].matchingMessages[].logMetadataobjectNo—
results[].matchingMessages[].createdAtstringNoISO 8601 timestamp.
totalintegerNo—
hasMorebooleanNo—
searchMetadataobjectNo—
searchMetadata.querystringNo—
searchMetadata.queryTypestringNo—
searchMetadata.processingTimeMsintegerNo—
Search threads
Loading...
Response 200
Loading...
See the ACP quickstart and SDK flow