> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.awork.com/apiv1/agent-threads/post-agents-threads-cancel-by-thread-id/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server. # Cancels the active run for the specified agent thread. POST https://api.awork.com/api/v1/agents/threads/{threadId}/cancel Cancels the active run in the specified personal-agent or custom-agent conversation and returns the thread. A successful cancellation also pauses dispatch of the next queued message. The user must have permission to contribute to the thread. Reference: https://developers.awork.com/apiv1/agent-threads/post-agents-threads-cancel-by-thread-id ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `threadId` (string, required) — The thread id. ## Response ### 200 OK - `id` (string, optional) — The id of the entity. - `createdOn` (string, optional) — The date this entity was created. - `createdBy` (string, optional) — The id of the user who created this entity. - `updatedBy` (string, optional) — The id of the user who last modified this entity. - `updatedOn` (string, optional) — The parent timestamp used to order thread queue snapshots, with subsecond precision. - `type` (string, optional, nullable) — The thread type. - `title` (string, optional, nullable) — The thread title. - `status` (string, optional, nullable) — The thread status. - `isReadOnly` (boolean, optional) — Whether the requester may only read this thread. - `isShared` (boolean, optional) — Whether this thread without project or task context currently has active shares. - `viewerAccess` (AgentThreadViewerAccessModel, optional) — Describes the requester's current shared-thread capabilities. - `contributors` (list of AiThreadContributorResponseModel, optional, nullable) — The users who explicitly joined this thread. - `activityUsers` (list of NestedUserModel, optional, nullable) — Current details for users referenced by membership and sharing activities on detail responses. - `queue` (list of AiThreadQueuedMessageResponseModel, optional, nullable) — The queued thread messages in dispatch order. - `agentId` (string, optional, nullable) — The agent used for the initial execution. - `agentNameSnapshot` (string, optional, nullable) — The immutable initial agent name. - `executionOwnerUserId` (string, optional, nullable) — The user whose permissions applied to the initial execution. - `executionTriggeredByUserId` (string, optional, nullable) — The user who triggered the initial execution. - `executionType` (string, optional, nullable) — The initial execution type. - `executionSourceId` (string, optional, nullable) — The entity that caused the initial execution. - `modelProvider` (string, optional, nullable) — The model provider. - `modelName` (string, optional, nullable) — The provider model name. - `parentThreadId` (string, optional, nullable) — The parent thread id. - `projectId` (string, optional, nullable) — The associated project id. - `taskId` (string, optional, nullable) — The associated task id. - `clientId` (string, optional, nullable) — The associated client id. - `documentId` (string, optional, nullable) — The associated document id. - `startedOn` (string, optional, nullable) — When execution started. - `completedOn` (string, optional, nullable) — When execution completed. - `lastActivityOn` (string, optional, nullable) — The latest activity timestamp. - `lastActivityBy` (string, optional, nullable) — The user responsible for the latest user-message activity. - `failureReason` (string, optional, nullable) — The failure reason. - `lastSequence` (long, optional) — The latest persisted event sequence. - `latestThreadUpdateSequence` (long, optional) — The latest event sequence that creates a thread update. - `hasUpdate` (boolean, optional) — Whether the requester has an unseen update. - `isArchived` (boolean, optional) — Whether the requester archived the thread. - `archivedOn` (string, optional, nullable) — When the requester archived the thread. - `isPinned` (boolean, optional) — Whether the requester pinned the thread. - `pinnedOrder` (double, optional, nullable) — The requester's pinned order. - `isAwaitingAction` (boolean, optional) — Whether the thread awaits user action. - `pendingBatchConfirmation` (PendingBatchConfirmationResponseModel, optional) — Represents a pending batch confirmation for an agent thread. - `pendingUserQuestion` (PendingUserQuestionResponseModel, optional) — Represents a pending user question for an agent thread. - `usedConnectors` (list of UsedConnectorResponseModel, optional, nullable) — Connectors used successfully in this thread on detail responses. - `contextWindowUsageRatio` (double, optional, nullable) — The context-window usage ratio on detail responses. - `rating` (string, optional, nullable) — The personal-thread rating on detail responses. ## Errors ### 404 Not Found Error Not Found - `code` (string, required) — The error code. - `description` (string, required) — The description of the error. - `link` (string, required) — The link to the API documentation page. - `details` (list of string, optional, nullable) — A list of details describing the error. - `validationErrors` (list of ValidationErrorResponse, optional, nullable) — If a validation error occurred, this contains the validation errors for each property. - `traceId` (string, optional, nullable) — The request trace id for tracking the request. ## Types ### AgentThreadViewerAccessModel Describes the requester's current shared-thread capabilities. - `canRead` (boolean, optional) — Whether the requester can read the thread. - `canWrite` (boolean, optional) — Whether the effective share grants Manage access. The field name preserves the existing API contract. - `isJoined` (boolean, optional) — Whether the requester joined the thread. - `canJoin` (boolean, optional) — Whether the requester can Join. - `canSend` (boolean, optional) — Whether the requester can send. - `canStop` (boolean, optional) — Whether the requester can stop active work. - `canManageThread` (boolean, optional) — Whether the requester can rename or delete the thread. - `canManageSharing` (boolean, optional) — Whether the requester can manage sharing. - `canLeave` (boolean, optional) — Whether the requester can leave. - `sendBlockedReason` (string, optional, nullable) — The reason that prevents sending. ### AiThreadContributorResponseModel Represents a user who explicitly joined an agent thread. - `id` (string, optional) — The contributor identifier. - `userId` (string, optional) — The user identifier. - `accessLevel` (string, optional, nullable) — The contributor access level. ### NestedUserModel - `id` (string, optional) — The identifier of the nested model. - `firstName` (string, optional, nullable) — The first name of the user. - `lastName` (string, optional, nullable) — The last name of the user. - `hasImage` (boolean, optional, nullable) — Whether this user has a profile image. ### AiThreadQueuedMessageResponseModel Represents one message request waiting in a thread queue. - `id` (string, optional) — The id of the entity. - `createdOn` (string, optional) — The date this entity was created. - `createdBy` (string, optional) — The id of the user who created this entity. - `updatedOn` (string, optional) — The date this entity was last modified. - `updatedBy` (string, optional) — The id of the user who last modified this entity. - `threadUpdatedOn` (string, optional, nullable) — The parent timestamp saved with an edit; absent on queue snapshot rows. - `threadId` (string, optional) — The owning thread id. - `queueOrder` (integer, optional) — The position in the queue. - `displayText` (string, optional, nullable) — The text shown in the queue. - `payload` (AgentThreadMessageRequestModel, optional) — Submits a follow-up message or answers a pending question in an agent conversation. - `attachments` (list of TemporaryFileReference, optional, nullable) — Attachment display metadata resolved by the server. This metadata is not part of the editable request. - `responsibleUserId` (string, optional) — The user whose permissions apply at dispatch time. - `blockedReason` (string, optional, nullable) — The stable reason that prevents automatic dispatch. ### PendingBatchConfirmationResponseModel Represents a pending batch confirmation for an agent thread. - `confirmationId` (string, optional, nullable) — The confirmation id. - `confirmationMessage` (string, optional, nullable) — The confirmation message. - `affectedItemCount` (integer, optional) — The affected item count. - `isDestructive` (boolean, optional) — Whether the action is destructive. - `confirmationDetails` (ConfirmationDetails, optional) — Detailed confirmation information for the UI with both English and German translations. - `pendingToolCalls` (list of AiToolCall, optional, nullable) — The tool calls awaiting confirmation. ### PendingUserQuestionResponseModel Represents a pending user question for an agent thread. - `toolCallId` (string, optional, nullable) — The tool call id. - `userQuestion` (UserQuestionDetails, optional) — Describes a user action that must complete before an agent run can resume. ### UsedConnectorResponseModel Identifies a used thread connector. - `id` (string, optional) — The connector identifier. - `name` (string, optional, nullable) — The connector name captured at its latest successful use. - `logoPath` (string, optional, nullable) — The predefined connector logo path, when available. ### ValidationErrorResponse The validation error response. - `property` (string, optional, nullable) — The name of the property that failed validation. - `message` (string, optional, nullable) — The reason why this property failed validation. ### AgentThreadMessageRequestModel Submits a follow-up message or answers a pending question in an agent conversation. - `content` (string, optional, nullable) — The message text. Required when no attachments are supplied. - `attachments` (list of AgentThreadAttachmentRequestModel, optional, nullable) — Up to 20 distinct files attached to this message. Each file can contain up to 20 MiB. Upload new files before submitting their identifiers. - `modelProvider` (string, optional, nullable) — The provider for a model override. Supply it together with modelName. - `modelName` (string, optional, nullable) — The model to use for this message. It must be available in the workspace. - `reasoningLevel` (string, optional, nullable) — The reasoning level for this message. Supported values depend on the selected model. - `toolAccess` (AgentToolAccessOptionsModel, optional) — Per-message agent tool access options. - `connectorIds` (list of string, optional, nullable) — The connector selection for this message. - `connectorConnections` (list of AgentMessageConnectorConnectionRequestModel, optional, nullable) — Connection choices for custom-agent connectors. These do not change agent settings. - `skillIds` (list of string, optional, nullable) — The skill selection for this message. - `answerToInterruptId` (string, optional, nullable) — The interrupt identifier returned with the question being answered. ### TemporaryFileReference Describes a temporary file attached to an agent message. - `id` (string, optional, nullable) — The resource id. - `name` (string, optional, nullable) — The display name. - `mimeType` (string, optional, nullable) — The file media type. - `sandboxPath` (string, optional, nullable) — The canonical sandbox path assigned after file promotion. - `downloadUrl` (string, optional, nullable) — The relative file download URL. ### ConfirmationDetails Detailed confirmation information for the UI with both English and German translations. - `headerMessageEn` (string, optional, nullable) — The English confirmation heading. - `headerMessageDe` (string, optional, nullable) — The German confirmation heading. - `confirmationQuestionEn` (string, optional, nullable) — The English confirmation question. - `confirmationQuestionDe` (string, optional, nullable) — The German confirmation question. - `confirmButtonTextEn` (string, optional, nullable) — The English confirm button label. - `confirmButtonTextDe` (string, optional, nullable) — The German confirm button label. - `cancelButtonTextEn` (string, optional, nullable) — The English cancel button label. - `cancelButtonTextDe` (string, optional, nullable) — The German cancel button label. - `isDestructive` (boolean, optional) — Whether the action is destructive. - `totalItemCount` (integer, optional) — The total item count. - `actions` (list of ConfirmationAction, optional, nullable) — The actions that require confirmation. ### AiToolCall Describes a tool call stored with an agent message. - `id` (string, optional, nullable) — The provider tool call identifier. - `toolName` (string, optional, nullable) — The runtime tool that was called. - `connectorId` (string, optional, nullable) — The connector that supplied the tool, if applicable. - `connectionId` (string, optional, nullable) — The connector connection used by the tool, if applicable. - `arguments` (map from string to any, optional, nullable) — The structured arguments supplied to the tool. - `response` (string, optional, nullable) — The serialized tool result. - `chartBlock` (string, optional, nullable) — The serialized native chart block produced by code mode, when present. ### UserQuestionDetails Describes a user action that must complete before an agent run can resume. - `question` (string, optional, nullable) — The user-facing question. - `options` (list of string, optional, nullable) — The bounded selectable answers. - `allowCustomText` (boolean, optional) — Whether a custom text answer is accepted. - `interactionType` (string, optional, nullable) — The structured interaction type. - `connectorId` (string, optional, nullable) — The connector that requires user action. - `connectionId` (string, optional, nullable) — The connection that requires reauthorization. - `connectorName` (string, optional, nullable) — The safe connector display name. - `connectionAction` (string, optional, nullable) — The enable or reconnect action. ### AgentThreadAttachmentRequestModel References an attached file. Supply exactly one of temporaryFileId or aworkFileId. - `temporaryFileId` (string, optional, nullable) — The identifier returned when uploading a temporary file. Do not also supply aworkFileId. - `aworkFileId` (string, optional, nullable) — The identifier of an existing awork file the caller can read. Do not also supply temporaryFileId. ### AgentToolAccessOptionsModel Per-message agent tool access options. - `awork` (boolean, optional) — Whether awork tools are enabled for this run. - `webSearch` (boolean, optional) — Whether web search is enabled for this run. - `googleGenAi` (boolean, optional) — Whether Google GenAI tools are enabled for this run. - `openAiImageGeneration` (boolean, optional) — Whether OpenAI image generation is enabled for this run. ### AgentMessageConnectorConnectionRequestModel Selects a connection for a Custom agent connector. - `connectorId` (string, optional) — The connector identifier. - `connectionId` (string, optional) — The connection identifier. ### ConfirmationAction A single action that requires confirmation with both English and German translations. - `actionDescriptionEn` (string, optional, nullable) — The English action description. - `actionDescriptionDe` (string, optional, nullable) — The German action description. - `itemNames` (list of string, optional, nullable) — The displayed affected item names. - `itemCount` (integer, optional) — The item count. - `hasMoreItems` (boolean, optional) — Whether more affected items exist. ## Examples **Response** ```json { "id": "23e68187-91d6-4f7e-8d31-e3f2c60d7427", "createdOn": "2022-03-11T15:33:47.100Z", "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "updatedBy": "3d844c62-7410-4df9-a5b2-78805c0ee260", "updatedOn": "2026-09-15T15:47:35.9586190Z", "type": "custom-agent", "title": "Weekly client status report", "status": "completed", "isReadOnly": false, "isShared": true, "viewerAccess": { "canRead": true, "canWrite": true, "isJoined": true, "canJoin": true, "canSend": true, "canStop": true, "canManageThread": true, "canManageSharing": true, "canLeave": true, "sendBlockedReason": "join-required" }, "contributors": [ { "id": "70c0f52e-d9af-45e7-b260-a75592a64e43", "userId": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "accessLevel": "manage" } ], "activityUsers": [ { "id": "80a2b26b-9fb3-42b5-b6dc-126c437cad5d", "firstName": "Carla", "lastName": "Creative", "hasImage": true } ], "queue": [ { "id": "23e68187-91d6-4f7e-8d31-e3f2c60d7427", "createdOn": "2022-03-11T15:33:47.100Z", "createdBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "updatedOn": "2022-03-11T21:15:00.100Z", "updatedBy": "3d844c62-7410-4df9-a5b2-78805c0ee260", "threadUpdatedOn": "2026-09-15T15:47:35.9586190Z", "threadId": "6cbb219e-839d-4d23-b273-3a78bbd842ae", "queueOrder": 1, "displayText": "Add client-ready risks and next steps to the status report.", "payload": { "content": "Summarize this project's progress, risks, and next steps.", "attachments": [ { "temporaryFileId": "af6ac9db-479a-49b8-8e1b-994ba79e940f", "aworkFileId": "7a5c994a-320a-4850-a7a8-dad86809d3ef" } ], "modelProvider": "openai", "modelName": "gpt-5.6-terra", "reasoningLevel": "medium", "toolAccess": { "awork": true, "webSearch": true, "googleGenAi": false, "openAiImageGeneration": false }, "connectorIds": [ "string" ], "connectorConnections": [ { "connectorId": "7e376777-7834-4af6-9eb8-da065f568d30", "connectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c" } ], "skillIds": [ "string" ], "answerToInterruptId": "interrupt_01K4CLIENTSTATUS" }, "attachments": [ { "id": "temp_01K4CLIENTBRIEF", "name": "acme-client-brief.pdf", "mimeType": "application/pdf", "sandboxPath": "context/uploads/awork-9ad6397243964b0b9e7d40b852cdebf8-acme-client-brief.pdf", "downloadUrl": "/api/v1/agents/threads/6cbb219e-839d-4d23-b273-3a78bbd842ae/artifacts/download?path=client-status-report.pdf" } ], "responsibleUserId": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "blockedReason": "interrupted" } ], "agentId": "4d22e163-2b4a-4d47-b51c-5b2217f84f57", "agentNameSnapshot": "Client Status Reporter", "executionOwnerUserId": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "executionTriggeredByUserId": "52c28884-c751-4e0b-820c-9abe8a524a29", "executionType": "chat", "executionSourceId": "c907b29e-f640-4639-910d-722623fd5b4a", "modelProvider": "openai", "modelName": "gpt-5.6-terra", "parentThreadId": "b5a57e4d-0eec-45b6-b55e-4b70bf0f2a18", "projectId": "c907b29e-f640-4639-910d-722623fd5b4a", "taskId": "d88ef8fa-e549-4ca6-96d8-83f5be9d37a2", "clientId": "61341e18-3e3f-4efb-b471-b781e64f69f7", "documentId": "5a442338-8da3-49e9-a702-b45d6f829d43", "startedOn": "2026-08-29T08:00:05Z", "completedOn": "2026-08-29T08:01:42Z", "lastActivityOn": "2026-08-29T08:01:42Z", "lastActivityBy": "9ad63972-4396-4b0b-9e7d-40b852cdebf8", "failureReason": "The model provider could not complete the run.", "lastSequence": 42, "latestThreadUpdateSequence": 42, "hasUpdate": false, "isArchived": false, "archivedOn": "2026-08-29T09:30:00Z", "isPinned": false, "pinnedOrder": 1, "isAwaitingAction": false, "pendingBatchConfirmation": { "confirmationId": "confirm_01K4CLIENTSTATUS", "confirmationMessage": "Delete 3 draft tasks from the Acme website project?", "affectedItemCount": 3, "isDestructive": true, "confirmationDetails": { "headerMessageEn": "Delete draft tasks", "headerMessageDe": "Entwurfsaufgaben löschen", "confirmationQuestionEn": "Delete 3 draft tasks from the Acme website project?", "confirmationQuestionDe": "3 Entwurfsaufgaben aus dem Acme-Website-Projekt löschen?", "confirmButtonTextEn": "Delete", "confirmButtonTextDe": "Löschen", "cancelButtonTextEn": "Cancel", "cancelButtonTextDe": "Abbrechen", "isDestructive": true, "totalItemCount": 3, "actions": [ { "actionDescriptionEn": "Delete draft tasks", "actionDescriptionDe": "Entwurfsaufgaben löschen", "itemNames": [ "string" ], "itemCount": 3, "hasMoreItems": false } ] }, "pendingToolCalls": [ { "id": "call_01K4CLIENTSTATUS", "toolName": "code_mode_execute", "connectorId": "7e376777-7834-4af6-9eb8-da065f568d30", "connectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c", "arguments": {}, "response": "{\"status\":\"completed\"}", "chartBlock": "{\"type\":\"chart\",\"version\":1,\"spec\":{\"style\":\"bar\",\"series\":[{\"name\":\"Revenue\",\"values\":[1,2]}]}}" } ] }, "pendingUserQuestion": { "toolCallId": "call_01K4CLIENTSTATUS", "userQuestion": { "question": "Should I send the client status report now?", "options": [ "string" ], "allowCustomText": false, "interactionType": "mcp_connection", "connectorId": "7e376777-7834-4af6-9eb8-da065f568d30", "connectionId": "af18602d-c8aa-4f63-a21e-5a7f59b2412c", "connectorName": "Client CRM", "connectionAction": "reconnect" } }, "usedConnectors": [ { "id": "7e376777-7834-4af6-9eb8-da065f568d30", "name": "Client CRM", "logoPath": "images/integrations/hubspot_icon.svg" } ], "contextWindowUsageRatio": 0.42, "rating": "positive" } ``` **SDK Code** ```python import requests url = "https://api.awork.com/api/v1/agents/threads/threadId/cancel" headers = {"Authorization": "Bearer "} response = requests.post(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.awork.com/api/v1/agents/threads/threadId/cancel'; const options = {method: 'POST', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.awork.com/api/v1/agents/threads/threadId/cancel" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.awork.com/api/v1/agents/threads/threadId/cancel") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.awork.com/api/v1/agents/threads/threadId/cancel") .header("Authorization", "Bearer ") .asString(); ``` ```php request('POST', 'https://api.awork.com/api/v1/agents/threads/threadId/cancel', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.awork.com/api/v1/agents/threads/threadId/cancel"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.awork.com/api/v1/agents/threads/threadId/cancel")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```