POST · leads:write

Cancel a task

Ask a running task to stop. Read the task again to confirm its final status.

Set up with your AI assistant

Paste the prompt into your coding assistant. It includes setup steps and a read-only connection check.

Request

Endpoint

POST https://leadsagent.io/api/v1/tasks/{id}/cancel

Set LEADSAGENT_API_KEY in your local environment. Send it in the X-API-Key header.

Bash · API base URL

export LEADSAGENT_API_BASE="https://leadsagent.io/api/v1"
# For a local backend:
# export LEADSAGENT_API_BASE="http://127.0.0.1:8001/api/v1"

Bash · curl

curl --fail-with-body --silent --show-error --request POST "$LEADSAGENT_API_BASE/tasks/$TASK_ID/cancel" -H "X-API-Key: $LEADSAGENT_API_KEY"

Replace TASK_ID with data.id from a task response. In PowerShell, use curl.exe and $env:LEADSAGENT_API_KEY. Save JSON in a file and pass --data-binary @request.json.

id (UUID): Required. The task ID.

Cancellation is a request. Work that already completed cannot be undone.
A completed or failed task can still be read.

Response

data is the task object with its latest status.

Example response

{
  "request_id": "6c4d0c26-8aa3-44b0-a50a-51b832b29465",
  "status": "success",
  "data": {
    "id": "73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "kind": "agent",
    "status": "running",
    "prompt": "Find 20 dentists in Austin with emails",
    "source": "API key · research-example",
    "max_leads": 20,
    "created_at": "2026-10-21T12:00:00+00:00",
    "updated_at": "2026-10-21T12:00:00+00:00",
    "steps": [],
    "lead_count": 0,
    "results_ready": false,
    "status_url": "/api/v1/tasks/73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4"
  },
  "meta": {}
}

Errors and retries explains status codes and retry rules. A successful request does not mean a background task has finished.

Read as Markdown