Endpoints // Bulk

Cancel a task

New

Last verified November 4, 2026

Stop a task an API key or an AI assistant started, for good. Items not started are never charged, and the results of the items done stay downloadable.

POST/v2/tasks/:taskId/cancel

Credits

Free.

Items that had not started are never charged.

Introduction

The Cancel a task endpoint stops a task for good. Items already in flight may finish and are charged as usual; items not started are never charged and read skipped in the results. The task then reads cancelled, and the results of the items done can be downloaded with Download task results. An item in flight finishes within the hour: until then, its row of the results file reads running, and Read task results by page waits for it.

Any key of the workspace that can read a task can cancel it, whichever key started it: a rotated key can still stop a task its predecessor created. This covers every task of the history that an API key or an AI assistant started (source is api or mcp), a List import included. A task a person started in the app or with Ask is stopped there: cancelling it here returns 403 TASK_STARTED_BY_A_PERSON.

Cancelling is free (0 credits), also at a zero balance, and final: a cancelled task is never resumed, and a new run needs a new task. Cancelling a task already cancelled answers it again. When the task has a webhookUrl, that URL receives the cancelled state.

Authorization

Name	Type	Required	Description
`apikey`	string	Yes	Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header.

Request

The route is POST /v2/tasks/:taskId/cancel.

Path parameters

Name	Type	Required	Description
`taskId`	string	Yes	The `id` of the task (UUID)

The request has no body.

Response structure

Field	Type	Description
`success`	boolean	`true` if the task was cancelled
`error`	`null`	Always `null` on success

data is the cancelled task, with the fields of Get a task and status set to cancelled. Its progress can still move while the items in flight finish, and credits.used stays null until the task has settled its credits (a List import counts them as it goes): read the task again to see the final counts.

quotas and metadata are the blocks of every V2 response: see Usage.

Errors

Status	Code	Meaning
`403`	`TASK_STARTED_BY_A_PERSON`	A person started this task in the app or with Ask: stop it there
`404`	`TASK_NOT_FOUND`	No task with this id in your workspace, or one your key may not read
`409`	`TASK_NOT_CANCELLABLE`	The task already completed or failed: there is nothing left to stop
`422`	`VALIDATION_ERROR`	`taskId` is not a UUID

Code examples

Remembered on every page

Code Examples

curl -X POST https://api.reversecontact.com/v2/tasks/7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

const taskId = "7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60";
const response = await fetch(`https://api.reversecontact.com/v2/tasks/${taskId}/cancel`, {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

const { data, error } = await response.json();
console.log(error ? error.code : `${data.status}, ${data.progress.remaining} items not started`);

import requests

task_id = "7b1e4c2a-5d3f-4e8b-9a6c-1f2d3e4b5a60"
response = requests.post(
    f"https://api.reversecontact.com/v2/tasks/{task_id}/cancel",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

payload = response.json()
print(payload["error"]["code"] if payload["error"] else payload["data"]["status"])

Example response

Example Response

{
  "success": true,
  "data": {
    "id": "5e8d2c1b-9a4f-4b3e-8c7d-6f5a4b3c2d10",
    "type": "enrich_persons",
    "entity": "persons",
    "status": "cancelled",
    "source": "api",
    "taskName": "Leads, Q4",
    "listId": null,
    "progress": {
      "total": 500,
      "processed": 120,
      "succeeded": 97,
      "failed": 23,
      "skipped": 0,
      "remaining": 380
    },
    "credits": { "estimated": 1000, "used": null },
    "estimatedSecondsRemaining": null,
    "error": null,
    "createdAt": "2026-11-04T10:02:00.000Z",
    "startedAt": "2026-11-04T10:02:01.000Z",
    "completedAt": "2026-11-04T10:04:30.000Z",
    "links": {
      "self": "/v2/tasks/5e8d2c1b-9a4f-4b3e-8c7d-6f5a4b3c2d10",
      "results": "/v2/tasks/5e8d2c1b-9a4f-4b3e-8c7d-6f5a4b3c2d10/results",
      "operation": null
    }
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 5472, "left": 4528 }
    }
  },
  "metadata": {
    "requestId": "2373b182-0821-45fb-b10f-37428d3b8087",
    "executionTimeMs": 48
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "TASK_NOT_CANCELLABLE",
    "message": "The task is completed and can no longer be cancelled"
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4528, "left": 5472 }
    }
  },
  "metadata": {
    "requestId": "d5f5c787-9f5f-42c4-9de8-f94144955cec",
    "executionTimeMs": 21
  }
}