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.
When the ticket type is loop, the platform resolves and pins the ticket's Loop contract, Agents, Project, exact environment, attachments, and budgets into an immutable run of the locked system.task-loop Metronome. The server then performs bounded worker/verifier iterations until independently verified success, a safety budget, a blocker, or cancellation stops the run.
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 prepare the thread without running it (`deferred`). Set queueInBatch with deferred mode to atomically persist the prepared execution in Batches. Loop tickets use the same system Metronome in both modes. |
| 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. Defaults to the task prompt. |
| content | string | No | Backwards-compatible alias for message. |
| task | string | No | Backwards-compatible alias for message. |
| queueWhenCapacityUnavailable | boolean | No | Persist blocking ticket work in Batches when runtime capacity is unavailable. Defaults to true on local appliances and false on cloud deployments. |
| queueInBatch | boolean | No | With deferred mode, atomically create the prepared thread, task-agent session, and durable Project ticket Batch receipt. Manual and stay-on-shelf jobs remain held until explicitly started. |
| batch | object | No | — |
| batch.name | string | No | Optional shelf label. Defaults to the ticket title. |
| batch.description | string | No | Human-readable description. |
| batch.startPolicy | manual | stay_on_shelf | when_capacity_available | No | — |
| batch.definition | object | No | Runtime options retained with the Project ticket action. |
| batch.metadata | object | No | Free-form metadata object. |
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 | permission_asked | completed | failed | archived | cancelled | deleted | No | Current lifecycle status. |
| thread.contextId | string | No | — |
| thread.contextName | string | No | — |
| thread.messageCount | integer | No | — |
| thread.lastMessageAt | string | No | — |
| thread.lastMessagePreview | string | No | — |
| thread.inputTokens | integer | No | — |
| thread.outputTokens | integer | No | — |
| thread.cacheTokens | integer | No | — |
| thread.totalTokens | integer | No | — |
| thread.agentCost | number | No | — |
| thread.agentCostUsd | number | No | — |
| thread.environmentCost | number | No | — |
| thread.environmentCostUsd | number | No | — |
| thread.totalCost | number | No | — |
| thread.totalCostUsd | number | No | — |
| thread.agentCT | integer | No | — |
| thread.environmentCT | integer | No | — |
| thread.totalCT | integer | No | — |
| thread.environmentMinutes | number | No | — |
| thread.environmentStorageGB | number | No | — |
| thread.attachments | object[] | 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.agentPhotoUrl | string | No | — |
| thread.agentAvatarUrl | string | No | — |
| thread.startedAt | string | No | ISO 8601 timestamp. |
| thread.completedAt | string | No | ISO 8601 timestamp. |
| thread.duration | string | No | — |
| thread.queuedInBatch | boolean | No | — |
| thread.batchJobId | string | No | — |
| thread.admissionReason | 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.schemaVersion | task_loop_v1 | 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.minimumScore | number | No | Minimum independently verified score required for success. |
| task.loop.maxDurationMinutes | integer | No | Wall-clock budget checked between worker/verifier iterations. |
| task.loop.maxDurationMs | integer | No | Normalized wall-clock budget returned by the runtime. |
| task.loop.regressionPolicy | continue | stop | No | Whether a materially regressing candidate stops the loop. |
| 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.schemaVersion | task_loop_v1 | 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.minimumScore | number | No | Minimum independently verified score required for success. |
| subtasks[].loop.maxDurationMinutes | integer | No | Wall-clock budget checked between worker/verifier iterations. |
| subtasks[].loop.maxDurationMs | integer | No | Normalized wall-clock budget returned by the runtime. |
| subtasks[].loop.regressionPolicy | continue | stop | No | Whether a materially regressing candidate stops the loop. |
| 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. |
| queuedInBatch | boolean | No | True when the request explicitly admitted this execution to Batches or runtime capacity moved it there. |
| batchJobId | string | No | — |
| batchJob | object | No | — |
| batchJob.id | string | Yes | Unique identifier. |
| batchJob.userId | string | Yes | User ID. |
| batchJob.organizationId | string | No | — |
| batchJob.createdByUserId | string | No | — |
| batchJob.ownerId | string | No | — |
| batchJob.ownerUserId | string | No | — |
| batchJob.ownerName | string | No | — |
| batchJob.ownerEmail | string | No | — |
| batchJob.ownerAvatarUrl | string | No | — |
| batchJob.owner | object | No | — |
| batchJob.owner.userId | string | Yes | User ID. |
| batchJob.owner.name | string | Yes | Human-readable name. |
| batchJob.owner.email | string | Yes | — |
| batchJob.owner.avatarUrl | string | Yes | — |
| batchJob.creatorId | string | No | — |
| batchJob.creatorUserId | string | No | — |
| batchJob.creatorName | string | No | — |
| batchJob.creatorEmail | string | No | — |
| batchJob.creatorAvatarUrl | string | No | — |
| batchJob.creator | object | No | — |
| batchJob.creator.userId | string | Yes | User ID. |
| batchJob.creator.name | string | Yes | Human-readable name. |
| batchJob.creator.email | string | Yes | — |
| batchJob.creator.avatarUrl | string | Yes | — |
| batchJob.name | string | Yes | Human-readable name. |
| batchJob.description | string | Yes | Human-readable description. |
| batchJob.targetKind | thread_run | metronome_run | evaluation_run | agent_optimization | project_ticket_action | Yes | — |
| batchJob.targetResourceId | string | No | — |
| batchJob.targetVersionId | string | No | — |
| batchJob.definition | object | Yes | Native target definition. A Thread Batch may reference an existing thread with threadId (or targetResourceId), or create a new thread when released by providing message and optional agentId, environmentId/computerId, projectId, title, attachments, skills, reasoning effort, and cost boundaries. |
| batchJob.startPolicy | manual | stay_on_shelf | when_capacity_available | Yes | manual is a one-shot shelf job started explicitly; stay_on_shelf is also started explicitly but returns to the bottom of its shelf after every successful execution; when_capacity_available is automatically released by the scheduler when runtime capacity permits. |
| batchJob.status | held | queued | dispatching | running | succeeded | failed | cancelled | Yes | Current lifecycle status. |
| batchJob.queueLane | string | Yes | — |
| batchJob.priority | integer | Yes | — |
| batchJob.position | integer | Yes | — |
| batchJob.maxAttempts | integer | Yes | — |
| batchJob.attemptCount | integer | Yes | — |
| batchJob.executionGeneration | integer | Yes | — |
| batchJob.availableAt | string | Yes | — |
| batchJob.waitReason | string | No | — |
| batchJob.nativeResourceType | string | No | — |
| batchJob.nativeResourceId | string | No | — |
| batchJob.sourceProjectId | string | No | — |
| batchJob.sourceTicketId | string | No | — |
| batchJob.permissionSet | string | Yes | — |
| batchJob.idempotencyKey | string | No | — |
| batchJob.leaseOwner | string | No | — |
| batchJob.leaseExpiresAt | string | No | — |
| batchJob.heartbeatAt | string | No | — |
| batchJob.lastError | string | No | — |
| batchJob.metadata | object | Yes | Free-form metadata object. |
| batchJob.createdAt | string | Yes | ISO 8601 timestamp. |
| batchJob.updatedAt | string | Yes | ISO 8601 timestamp. |
| batchJob.queuedAt | string | No | — |
| batchJob.startedAt | string | No | ISO 8601 timestamp. |
| batchJob.completedAt | string | No | ISO 8601 timestamp. |
| execution | object | No | — |
| execution.success | boolean | No | Whether the request succeeded. |
| execution.kind | thread | system_workflow | No | — |
| execution.owner | server | No | — |
| execution.state | string | No | Current native execution state. Loop responses use the deterministic repeat-until result state when available. |
| execution.cancelled | boolean | No | — |
| execution.systemWorkflow | object | No | — |
| execution.systemWorkflow.key | system.task-loop | No | — |
| execution.systemWorkflow.version | integer | No | — |
| execution.systemWorkflow.digest | string | No | — |
| execution.loopRun | object | No | — |
| execution.loopRun.status | running | succeeded | exhausted | blocked | failed | cancelled | Yes | Current lifecycle status. |
| execution.loopRun.stopReason | string | No | — |
| execution.loopRun.iterationCount | integer | Yes | — |
| execution.loopRun.noProgressCount | integer | Yes | — |
| execution.loopRun.bestScore | number | No | — |
| execution.loopRun.bestIteration | integer | No | — |
| execution.loopRun.latestEvaluation | object | No | Latest independent verifier verdict, evidence, criteria coverage, critique, and next step. |
| execution.loopRun.usage | object | Yes | — |
| execution.loopRun.usage.durationMs | number | Yes | — |
| execution.loopRun.usage.inputTokens | number | Yes | — |
| execution.loopRun.usage.outputTokens | number | Yes | — |
| execution.loopRun.usage.computeTokens | number | Yes | — |
| execution.loopRun.usage.costUsd | number | Yes | — |
| execution.loopRun.usage.actions | number | Yes | — |
| 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.usage.computeTokens | number | No | — |
| execution.usage.costUsd | 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 | permission_asked | completed | failed | archived | cancelled | deleted | No | Current lifecycle status. |
| thread.contextId | string | No | — |
| thread.contextName | string | No | — |
| thread.messageCount | integer | No | — |
| thread.lastMessageAt | string | No | — |
| thread.lastMessagePreview | string | No | — |
| thread.inputTokens | integer | No | — |
| thread.outputTokens | integer | No | — |
| thread.cacheTokens | integer | No | — |
| thread.totalTokens | integer | No | — |
| thread.agentCost | number | No | — |
| thread.agentCostUsd | number | No | — |
| thread.environmentCost | number | No | — |
| thread.environmentCostUsd | number | No | — |
| thread.totalCost | number | No | — |
| thread.totalCostUsd | number | No | — |
| thread.agentCT | integer | No | — |
| thread.environmentCT | integer | No | — |
| thread.totalCT | integer | No | — |
| thread.environmentMinutes | number | No | — |
| thread.environmentStorageGB | number | No | — |
| thread.attachments | object[] | 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.agentPhotoUrl | string | No | — |
| thread.agentAvatarUrl | string | No | — |
| thread.startedAt | string | No | ISO 8601 timestamp. |
| thread.completedAt | string | No | ISO 8601 timestamp. |
| thread.duration | string | No | — |
| thread.queuedInBatch | boolean | No | — |
| thread.batchJobId | string | No | — |
| thread.admissionReason | 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.schemaVersion | task_loop_v1 | 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.minimumScore | number | No | Minimum independently verified score required for success. |
| task.loop.maxDurationMinutes | integer | No | Wall-clock budget checked between worker/verifier iterations. |
| task.loop.maxDurationMs | integer | No | Normalized wall-clock budget returned by the runtime. |
| task.loop.regressionPolicy | continue | stop | No | Whether a materially regressing candidate stops the loop. |
| 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.schemaVersion | task_loop_v1 | 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.minimumScore | number | No | Minimum independently verified score required for success. |
| subtasks[].loop.maxDurationMinutes | integer | No | Wall-clock budget checked between worker/verifier iterations. |
| subtasks[].loop.maxDurationMs | integer | No | Normalized wall-clock budget returned by the runtime. |
| subtasks[].loop.regressionPolicy | continue | stop | No | Whether a materially regressing candidate stops the loop. |
| 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. |
| queuedInBatch | boolean | No | True when the request explicitly admitted this execution to Batches or runtime capacity moved it there. |
| batchJobId | string | No | — |
| batchJob | object | No | — |
| batchJob.id | string | Yes | Unique identifier. |
| batchJob.userId | string | Yes | User ID. |
| batchJob.organizationId | string | No | — |
| batchJob.createdByUserId | string | No | — |
| batchJob.ownerId | string | No | — |
| batchJob.ownerUserId | string | No | — |
| batchJob.ownerName | string | No | — |
| batchJob.ownerEmail | string | No | — |
| batchJob.ownerAvatarUrl | string | No | — |
| batchJob.owner | object | No | — |
| batchJob.owner.userId | string | Yes | User ID. |
| batchJob.owner.name | string | Yes | Human-readable name. |
| batchJob.owner.email | string | Yes | — |
| batchJob.owner.avatarUrl | string | Yes | — |
| batchJob.creatorId | string | No | — |
| batchJob.creatorUserId | string | No | — |
| batchJob.creatorName | string | No | — |
| batchJob.creatorEmail | string | No | — |
| batchJob.creatorAvatarUrl | string | No | — |
| batchJob.creator | object | No | — |
| batchJob.creator.userId | string | Yes | User ID. |
| batchJob.creator.name | string | Yes | Human-readable name. |
| batchJob.creator.email | string | Yes | — |
| batchJob.creator.avatarUrl | string | Yes | — |
| batchJob.name | string | Yes | Human-readable name. |
| batchJob.description | string | Yes | Human-readable description. |
| batchJob.targetKind | thread_run | metronome_run | evaluation_run | agent_optimization | project_ticket_action | Yes | — |
| batchJob.targetResourceId | string | No | — |
| batchJob.targetVersionId | string | No | — |
| batchJob.definition | object | Yes | Native target definition. A Thread Batch may reference an existing thread with threadId (or targetResourceId), or create a new thread when released by providing message and optional agentId, environmentId/computerId, projectId, title, attachments, skills, reasoning effort, and cost boundaries. |
| batchJob.startPolicy | manual | stay_on_shelf | when_capacity_available | Yes | manual is a one-shot shelf job started explicitly; stay_on_shelf is also started explicitly but returns to the bottom of its shelf after every successful execution; when_capacity_available is automatically released by the scheduler when runtime capacity permits. |
| batchJob.status | held | queued | dispatching | running | succeeded | failed | cancelled | Yes | Current lifecycle status. |
| batchJob.queueLane | string | Yes | — |
| batchJob.priority | integer | Yes | — |
| batchJob.position | integer | Yes | — |
| batchJob.maxAttempts | integer | Yes | — |
| batchJob.attemptCount | integer | Yes | — |
| batchJob.executionGeneration | integer | Yes | — |
| batchJob.availableAt | string | Yes | — |
| batchJob.waitReason | string | No | — |
| batchJob.nativeResourceType | string | No | — |
| batchJob.nativeResourceId | string | No | — |
| batchJob.sourceProjectId | string | No | — |
| batchJob.sourceTicketId | string | No | — |
| batchJob.permissionSet | string | Yes | — |
| batchJob.idempotencyKey | string | No | — |
| batchJob.leaseOwner | string | No | — |
| batchJob.leaseExpiresAt | string | No | — |
| batchJob.heartbeatAt | string | No | — |
| batchJob.lastError | string | No | — |
| batchJob.metadata | object | Yes | Free-form metadata object. |
| batchJob.createdAt | string | Yes | ISO 8601 timestamp. |
| batchJob.updatedAt | string | Yes | ISO 8601 timestamp. |
| batchJob.queuedAt | string | No | — |
| batchJob.startedAt | string | No | ISO 8601 timestamp. |
| batchJob.completedAt | string | No | ISO 8601 timestamp. |
| execution | object | No | — |
| execution.success | boolean | No | Whether the request succeeded. |
| execution.kind | thread | system_workflow | No | — |
| execution.owner | server | No | — |
| execution.state | string | No | Current native execution state. Loop responses use the deterministic repeat-until result state when available. |
| execution.cancelled | boolean | No | — |
| execution.systemWorkflow | object | No | — |
| execution.systemWorkflow.key | system.task-loop | No | — |
| execution.systemWorkflow.version | integer | No | — |
| execution.systemWorkflow.digest | string | No | — |
| execution.loopRun | object | No | — |
| execution.loopRun.status | running | succeeded | exhausted | blocked | failed | cancelled | Yes | Current lifecycle status. |
| execution.loopRun.stopReason | string | No | — |
| execution.loopRun.iterationCount | integer | Yes | — |
| execution.loopRun.noProgressCount | integer | Yes | — |
| execution.loopRun.bestScore | number | No | — |
| execution.loopRun.bestIteration | integer | No | — |
| execution.loopRun.latestEvaluation | object | No | Latest independent verifier verdict, evidence, criteria coverage, critique, and next step. |
| execution.loopRun.usage | object | Yes | — |
| execution.loopRun.usage.durationMs | number | Yes | — |
| execution.loopRun.usage.inputTokens | number | Yes | — |
| execution.loopRun.usage.outputTokens | number | Yes | — |
| execution.loopRun.usage.computeTokens | number | Yes | — |
| execution.loopRun.usage.costUsd | number | Yes | — |
| execution.loopRun.usage.actions | number | Yes | — |
| 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.usage.computeTokens | number | No | — |
| execution.usage.costUsd | number | No | — |
| execution.error | string | No | — |
402Insufficient budget
None.
409Task is blocked by incomplete dependencies
None.