Threads API

Get a thread

Read one thread's metadata and derived status.

GET/api/v1/tasks/{taskId}

Returns the thread's metadata: its current execution, title and derived status. It does not return the conversation; personal tokens cannot read transcript history. Reading never wakes the workspace, so polling it is free.

Requires a personal API token with the tasks:read scope, sent as Authorization: Bearer over HTTPS.

Path parameters

taskIdstring (UUID)required: The thread. A thread that is not yours answers 404, never 403.

Returns

200 OK with the thread's metadata.

Response fields

taskIdstring (UUID)required: The thread.
userIdstringrequired: Your account. Every endpoint only ever returns your own threads.
projectIdstring (UUID)required: The project the thread belongs to.
executionobjectrequired: The harness, connection and model the thread currently runs on. Send messages with execution.id: a fork or a harness switch changes it.
titlestringrequired: Shown in the sidebar.
statusSummary"working" | "needs_you" | "ready" | "done" | "failed" | "limited"required: Derived from what is running and linked: Working, Needs you, Ready to review, Done, Failed or Limited. A finished reply alone does not mean done.
sandboxIdstring | nullrequired: The workspace machine, once one has been assigned.
lastSeqintegerrequired: Sequence number of the latest transcript item. It grows as the thread works.
createdAtstring (ISO 8601)required: When the thread was created.
updatedAtstring (ISO 8601)required: Last change to the thread.
lastMessageAtstring (ISO 8601) | nulloptional: Your latest message. Replies and background activity do not move it.
pinnedAtstring (ISO 8601) | nullrequired: Set when you pinned the thread.
archivedAtstring (ISO 8601) | nullrequired: Set when the thread is archived.
sourceLabelstring | nullrequired: Repository or project name shown in the sidebar.
branchLabelstring | nullrequired: Branch shown in the sidebar.
parentTaskIdstring (UUID) | nulloptional: Set on a child thread started by another thread's agent.
forkedFromTaskIdstring (UUID) | nulloptional: Set on a fork.
pullRequestobject | nulloptional: The linked pull request with its state, checks and review, when there is one.

Errors

Errors are JSON: { "version": 1, "error": { "code", "message" } }. See Errors for retry advice.

401unauthorized: The bearer token is missing, invalid or revoked.
403forbidden: The token does not have the tasks:read scope, or the account is suspended.
404not_found: The thread does not exist, is not yours, or the id is not a UUID.