Run task thread
POST
/v1/tasks/{taskId}/run-threadCreate a new thread and durable agent-session attempt for a task, link both to the task, and either execute synchronously or return the queued execution for deferred processing.
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 |
|---|---|---|---|---|
| taskId | path | string | Yes | Task ID |
Query parameters
None.
Header parameters
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | string | No | A client-generated key that makes retries return the original task-agent attempt without launching another execution. |
Body schema
Content type: application/json · Optional
| Field | Type | Required | Description |
|---|---|---|---|
| executionMode | blocking | deferred | No | Execute before returning (`blocking`) or return the queued thread for an external live execution pipeline (`deferred`). |
| idempotencyKey | string | No | Body alternative to the Idempotency-Key header. If both are supplied, they must match. |
| title | string | No | Optional title override for the created thread. |
| environmentId | string | No | Computer ID. |
| agentId | string | No | Agent ID. |
| moveToInProgress | boolean | No | — |
| metadata | object | No | Free-form metadata object. |
| message | string | No | Optional execution message for blocking mode. Defaults to the task prompt. |
| content | string | No | Backwards-compatible alias for message. |
| task | string | No | Backwards-compatible alias for message. |
What the API returns
Each response code below includes the documented payload shape for the ACP API.
200Existing task-agent attempt returned for an idempotent replayapplication/json
| Field | Type | Required | Description |
|---|---|---|---|
| thread | object | No | — |
| thread.id | string | No | Unique identifier. |
| thread.userId | string | No | User ID. |
| thread.organizationId | string | No | — |
| thread.createdByUserId | string | No | — |
| thread.projectId | string | No | Project ID. |
| thread.environmentId | string | No | Computer ID. |
| thread.agentId | string | No | Agent ID. |
| thread.title | string | No | Display title. |
| thread.task | string | No | — |
| thread.appId | string | No | — |
| thread.status | active | running | completed | failed | cancelled | No | Current lifecycle status. |
| thread.messageCount | integer | No | — |
| thread.lastMessageAt | string | No | — |
| thread.lastMessagePreview | string | No | — |
| thread.inputTokens | integer | No | — |
| thread.outputTokens | integer | No | — |
| thread.totalCost | number | No | — |
| thread.environmentMinutes | number | No | — |
| thread.metadata | object | No | Free-form metadata object. |
| thread.teamExecution | object | No | — |
| thread.teamExecution.mode | team | No | — |
| thread.teamExecution.teamAgentId | string | No | — |
| thread.teamExecution.teamAgentName | string | No | — |
| thread.teamExecution.orchestrator | object | No | — |
| thread.teamExecution.orchestrator.agentId | string | No | Agent ID. |
| thread.teamExecution.orchestrator.agentName | string | No | — |
| thread.teamExecution.orchestrator.claudeAgentName | string | No | — |
| thread.teamExecution.subagents | object[] | No | — |
| thread.teamExecution.subagents[].agentId | string | No | Agent ID. |
| thread.teamExecution.subagents[].agentName | string | No | — |
| thread.teamExecution.subagents[].claudeAgentName | string | No | — |
| thread.subagentActivity | object[] | No | — |
| thread.subagentActivity[].agentId | string | No | Agent ID. |
| thread.subagentActivity[].agentName | string | No | — |
| thread.subagentActivity[].claudeAgentName | string | No | — |
| thread.subagentActivity[].eventCount | integer | No | — |
| thread.subagentActivity[].lastActiveAt | string | No | — |
| thread.subagentActivity[].teamAgentId | string | No | — |
| thread.subagentActivity[].teamAgentName | string | No | — |
| thread.environmentName | string | No | — |
| thread.agentName | string | No | — |
| thread.createdAt | string | No | ISO 8601 timestamp. |
| thread.updatedAt | string | No | ISO 8601 timestamp. |
| task | object | No | — |
| task.id | string | No | Unique identifier. |
| task.userId | string | No | User ID. |
| task.organizationId | string | No | — |
| task.createdByUserId | string | No | — |
| task.creator | object | No | — |
| task.creator.type | user | agent | Yes | — |
| task.creator.userId | string | No | User ID. |
| task.creator.agentId | string | No | Agent ID. |
| task.creator.name | string | No | Human-readable name. |
| task.creator.avatarUrl | string | No | — |
| task.projectId | string | No | Project ID. |
| task.releaseId | string | No | — |
| task.title | string | No | Display title. |
| task.description | string | No | Human-readable description. |
| task.status | backlog | todo | in_progress | blocked | in_review | done | canceled | No | Current lifecycle status. |
| task.priority | low | medium | high | urgent | No | — |
| task.type | task | subtask | loop | No | — |
| task.parentTaskId | string | No | — |
| task.loop | object | No | — |
| task.loop.enabled | boolean | No | — |
| task.loop.goal | string | No | End goal the loop should reach. |
| task.loop.endGoal | string | No | Alias for goal. |
| task.loop.progressSignal | string | No | Observable signal that shows each iteration is making progress. |
| task.loop.verificationCriteria | string | No | How the verifier should judge each iteration. |
| task.loop.successCriteria | string | No | Objective condition that stops the loop successfully. |
| task.loop.maxIterations | integer | No | — |
| task.loop.noProgressLimit | integer | No | — |
| task.loop.workerAgentId | string | No | — |
| task.loop.verifierAgentId | string | No | — |
| task.sprintId | string | No | — |
| task.assigneeAgentId | string | No | — |
| task.dependencyIds | string[] | No | — |
| task.linkedThreadIds | string[] | No | — |
| task.lastStartedThreadId | string | No | — |
| task.scheduledStartAt | string | No | — |
| task.scheduledEndAt | string | No | — |
| task.dueAt | string | No | — |
| task.completedAt | string | No | ISO 8601 timestamp. |
| task.sortOrder | number | No | — |
| task.metadata | object | No | Free-form metadata object. |
| task.createdAt | string | No | ISO 8601 timestamp. |
| task.updatedAt | string | No | ISO 8601 timestamp. |
| subtasks | object[] | No | — |
| subtasks[].id | string | No | Unique identifier. |
| subtasks[].title | string | No | Display title. |
| subtasks[].description | string | No | Human-readable description. |
| subtasks[].status | backlog | todo | in_progress | blocked | in_review | done | canceled | No | Current lifecycle status. |
| subtasks[].priority | low | medium | high | urgent | No | — |
| subtasks[].type | task | subtask | loop | No | — |
| subtasks[].parentTaskId | string | No | — |
| subtasks[].loop | object | No | — |
| subtasks[].loop.enabled | boolean | No | — |
| subtasks[].loop.goal | string | No | End goal the loop should reach. |
| subtasks[].loop.endGoal | string | No | Alias for goal. |
| subtasks[].loop.progressSignal | string | No | Observable signal that shows each iteration is making progress. |
| subtasks[].loop.verificationCriteria | string | No | How the verifier should judge each iteration. |
| subtasks[].loop.successCriteria | string | No | Objective condition that stops the loop successfully. |
| subtasks[].loop.maxIterations | integer | No | — |
| subtasks[].loop.noProgressLimit | integer | No | — |
| subtasks[].loop.workerAgentId | string | No | — |
| subtasks[].loop.verifierAgentId | string | No | — |
| subtasks[].assigneeAgentId | string | No | — |
| subtasks[].dependencyIds | string[] | No | — |
| subtasks[].linkedThreadIds | string[] | No | — |
| subtasks[].lastStartedThreadId | string | No | — |
| subtasks[].scheduledStartAt | string | No | — |
| subtasks[].scheduledEndAt | string | No | — |
| subtasks[].dueAt | string | No | — |
| subtasks[].reviewRequired | boolean | No | — |
| subtasks[].reviewerActorId | string | No | — |
| subtasks[].reviewerActorKind | string | No | — |
| subtasks[].reviewerName | string | No | — |
| agentSession | object | No | — |
| agentSession.id | string | Yes | Unique identifier. |
| agentSession.userId | string | Yes | User ID. |
| agentSession.organizationId | string | No | — |
| agentSession.createdByUserId | string | No | — |
| agentSession.projectId | string | No | Project ID. |
| agentSession.taskId | string | Yes | — |
| agentSession.threadId | string | Yes | Thread ID. |
| agentSession.agentId | string | No | Agent ID. |
| agentSession.environmentId | string | No | Computer ID. |
| agentSession.state | queued | active | awaiting_input | completed | failed | canceled | stale | Yes | — |
| agentSession.triggerKind | manual | automation | schedule | api | retry | Yes | — |
| agentSession.attemptNumber | integer | Yes | — |
| agentSession.idempotencyKey | string | Yes | — |
| agentSession.executionConfig | object | No | — |
| agentSession.limits | object | No | — |
| agentSession.inputTokens | integer | Yes | — |
| agentSession.outputTokens | integer | Yes | — |
| agentSession.costUsd | number | No | — |
| agentSession.errorCode | string | No | — |
| agentSession.errorMessage | string | No | — |
| agentSession.startedAt | string | No | ISO 8601 timestamp. |
| agentSession.completedAt | string | No | ISO 8601 timestamp. |
| agentSession.metadata | object | No | Free-form metadata object. |
| agentSession.createdAt | string | Yes | ISO 8601 timestamp. |
| agentSession.updatedAt | string | Yes | ISO 8601 timestamp. |
| executionStarted | boolean | No | True when the request executed the thread; false when deferred execution was requested. |
| idempotentReplay | boolean | No | True when the request returned a previously created attempt and did not launch execution again. |
| execution | object | No | — |
| execution.success | boolean | No | Whether the request succeeded. |
| execution.response | string | No | — |
| execution.actions | string[] | No | — |
| execution.durationMs | number | No | — |
| execution.usage | object | No | — |
| execution.usage.inputTokens | number | No | — |
| execution.usage.outputTokens | number | No | — |
| execution.error | string | No | — |
201Task thread and durable agent-session attempt createdapplication/json
| Field | Type | Required | Description |
|---|---|---|---|
| thread | object | No | — |
| thread.id | string | No | Unique identifier. |
| thread.userId | string | No | User ID. |
| thread.organizationId | string | No | — |
| thread.createdByUserId | string | No | — |
| thread.projectId | string | No | Project ID. |
| thread.environmentId | string | No | Computer ID. |
| thread.agentId | string | No | Agent ID. |
| thread.title | string | No | Display title. |
| thread.task | string | No | — |
| thread.appId | string | No | — |
| thread.status | active | running | completed | failed | cancelled | No | Current lifecycle status. |
| thread.messageCount | integer | No | — |
| thread.lastMessageAt | string | No | — |
| thread.lastMessagePreview | string | No | — |
| thread.inputTokens | integer | No | — |
| thread.outputTokens | integer | No | — |
| thread.totalCost | number | No | — |
| thread.environmentMinutes | number | No | — |
| thread.metadata | object | No | Free-form metadata object. |
| thread.teamExecution | object | No | — |
| thread.teamExecution.mode | team | No | — |
| thread.teamExecution.teamAgentId | string | No | — |
| thread.teamExecution.teamAgentName | string | No | — |
| thread.teamExecution.orchestrator | object | No | — |
| thread.teamExecution.orchestrator.agentId | string | No | Agent ID. |
| thread.teamExecution.orchestrator.agentName | string | No | — |
| thread.teamExecution.orchestrator.claudeAgentName | string | No | — |
| thread.teamExecution.subagents | object[] | No | — |
| thread.teamExecution.subagents[].agentId | string | No | Agent ID. |
| thread.teamExecution.subagents[].agentName | string | No | — |
| thread.teamExecution.subagents[].claudeAgentName | string | No | — |
| thread.subagentActivity | object[] | No | — |
| thread.subagentActivity[].agentId | string | No | Agent ID. |
| thread.subagentActivity[].agentName | string | No | — |
| thread.subagentActivity[].claudeAgentName | string | No | — |
| thread.subagentActivity[].eventCount | integer | No | — |
| thread.subagentActivity[].lastActiveAt | string | No | — |
| thread.subagentActivity[].teamAgentId | string | No | — |
| thread.subagentActivity[].teamAgentName | string | No | — |
| thread.environmentName | string | No | — |
| thread.agentName | string | No | — |
| thread.createdAt | string | No | ISO 8601 timestamp. |
| thread.updatedAt | string | No | ISO 8601 timestamp. |
| task | object | No | — |
| task.id | string | No | Unique identifier. |
| task.userId | string | No | User ID. |
| task.organizationId | string | No | — |
| task.createdByUserId | string | No | — |
| task.creator | object | No | — |
| task.creator.type | user | agent | Yes | — |
| task.creator.userId | string | No | User ID. |
| task.creator.agentId | string | No | Agent ID. |
| task.creator.name | string | No | Human-readable name. |
| task.creator.avatarUrl | string | No | — |
| task.projectId | string | No | Project ID. |
| task.releaseId | string | No | — |
| task.title | string | No | Display title. |
| task.description | string | No | Human-readable description. |
| task.status | backlog | todo | in_progress | blocked | in_review | done | canceled | No | Current lifecycle status. |
| task.priority | low | medium | high | urgent | No | — |
| task.type | task | subtask | loop | No | — |
| task.parentTaskId | string | No | — |
| task.loop | object | No | — |
| task.loop.enabled | boolean | No | — |
| task.loop.goal | string | No | End goal the loop should reach. |
| task.loop.endGoal | string | No | Alias for goal. |
| task.loop.progressSignal | string | No | Observable signal that shows each iteration is making progress. |
| task.loop.verificationCriteria | string | No | How the verifier should judge each iteration. |
| task.loop.successCriteria | string | No | Objective condition that stops the loop successfully. |
| task.loop.maxIterations | integer | No | — |
| task.loop.noProgressLimit | integer | No | — |
| task.loop.workerAgentId | string | No | — |
| task.loop.verifierAgentId | string | No | — |
| task.sprintId | string | No | — |
| task.assigneeAgentId | string | No | — |
| task.dependencyIds | string[] | No | — |
| task.linkedThreadIds | string[] | No | — |
| task.lastStartedThreadId | string | No | — |
| task.scheduledStartAt | string | No | — |
| task.scheduledEndAt | string | No | — |
| task.dueAt | string | No | — |
| task.completedAt | string | No | ISO 8601 timestamp. |
| task.sortOrder | number | No | — |
| task.metadata | object | No | Free-form metadata object. |
| task.createdAt | string | No | ISO 8601 timestamp. |
| task.updatedAt | string | No | ISO 8601 timestamp. |
| subtasks | object[] | No | — |
| subtasks[].id | string | No | Unique identifier. |
| subtasks[].title | string | No | Display title. |
| subtasks[].description | string | No | Human-readable description. |
| subtasks[].status | backlog | todo | in_progress | blocked | in_review | done | canceled | No | Current lifecycle status. |
| subtasks[].priority | low | medium | high | urgent | No | — |
| subtasks[].type | task | subtask | loop | No | — |
| subtasks[].parentTaskId | string | No | — |
| subtasks[].loop | object | No | — |
| subtasks[].loop.enabled | boolean | No | — |
| subtasks[].loop.goal | string | No | End goal the loop should reach. |
| subtasks[].loop.endGoal | string | No | Alias for goal. |
| subtasks[].loop.progressSignal | string | No | Observable signal that shows each iteration is making progress. |
| subtasks[].loop.verificationCriteria | string | No | How the verifier should judge each iteration. |
| subtasks[].loop.successCriteria | string | No | Objective condition that stops the loop successfully. |
| subtasks[].loop.maxIterations | integer | No | — |
| subtasks[].loop.noProgressLimit | integer | No | — |
| subtasks[].loop.workerAgentId | string | No | — |
| subtasks[].loop.verifierAgentId | string | No | — |
| subtasks[].assigneeAgentId | string | No | — |
| subtasks[].dependencyIds | string[] | No | — |
| subtasks[].linkedThreadIds | string[] | No | — |
| subtasks[].lastStartedThreadId | string | No | — |
| subtasks[].scheduledStartAt | string | No | — |
| subtasks[].scheduledEndAt | string | No | — |
| subtasks[].dueAt | string | No | — |
| subtasks[].reviewRequired | boolean | No | — |
| subtasks[].reviewerActorId | string | No | — |
| subtasks[].reviewerActorKind | string | No | — |
| subtasks[].reviewerName | string | No | — |
| agentSession | object | No | — |
| agentSession.id | string | Yes | Unique identifier. |
| agentSession.userId | string | Yes | User ID. |
| agentSession.organizationId | string | No | — |
| agentSession.createdByUserId | string | No | — |
| agentSession.projectId | string | No | Project ID. |
| agentSession.taskId | string | Yes | — |
| agentSession.threadId | string | Yes | Thread ID. |
| agentSession.agentId | string | No | Agent ID. |
| agentSession.environmentId | string | No | Computer ID. |
| agentSession.state | queued | active | awaiting_input | completed | failed | canceled | stale | Yes | — |
| agentSession.triggerKind | manual | automation | schedule | api | retry | Yes | — |
| agentSession.attemptNumber | integer | Yes | — |
| agentSession.idempotencyKey | string | Yes | — |
| agentSession.executionConfig | object | No | — |
| agentSession.limits | object | No | — |
| agentSession.inputTokens | integer | Yes | — |
| agentSession.outputTokens | integer | Yes | — |
| agentSession.costUsd | number | No | — |
| agentSession.errorCode | string | No | — |
| agentSession.errorMessage | string | No | — |
| agentSession.startedAt | string | No | ISO 8601 timestamp. |
| agentSession.completedAt | string | No | ISO 8601 timestamp. |
| agentSession.metadata | object | No | Free-form metadata object. |
| agentSession.createdAt | string | Yes | ISO 8601 timestamp. |
| agentSession.updatedAt | string | Yes | ISO 8601 timestamp. |
| executionStarted | boolean | No | True when the request executed the thread; false when deferred execution was requested. |
| idempotentReplay | boolean | No | True when the request returned a previously created attempt and did not launch execution again. |
| execution | object | No | — |
| execution.success | boolean | No | Whether the request succeeded. |
| execution.response | string | No | — |
| execution.actions | string[] | No | — |
| execution.durationMs | number | No | — |
| execution.usage | object | No | — |
| execution.usage.inputTokens | number | No | — |
| execution.usage.outputTokens | number | No | — |
| execution.error | string | No | — |
402Insufficient budget
None.
409Task is blocked by incomplete dependencies
None.