Cancel a task

Cancel a background task. A queued task is cancelled at once. A running one is asked to stop: it stays running with cancelRequestedAt until its next checkpoint (an import stops after its current batch of rows), then ends cancelled; what it already did stays done. Asking again changes nothing; a finished task fails with INVALID_STATE.

Scope: raiz:tasks:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; idempotent, safe to retry
Limits: request body up to 32 KB, response up to 1 MB
CLI: arbol raiz tasks cancel · MCP tool: raiz_tasks_cancel

POST

https://api.getarbol.com/v1/raiz/tasks/{taskId}/cancel

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope raiz:tasks:write. Get an API key.

Path parameters

taskId
string
required
Task id.

pattern: ^job_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$

Request body JSON required

Returns

200

Successful operation.

JSON

success
boolean
required
data
object
required
- attemptCount
  integer
  required
  Attempts the task has made so far, retries included. A task that works in slices counts one attempt for all of them.
  
  minimum: 0
- cancelRequestedAt
  string | null
  required
  When someone asked the running task to stop. It ends cancelled at its next checkpoint, keeping what it already did.
  
  format: date-time
- createdAt
  string
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- createdBy
  string | null
  required
  The person or client that started it.
- endedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- errorCode
  string | null
  required
  Why it failed, when it failed.
- id
  string
  required
  Task id.
  
  pattern: ^job_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- kind
  contact_import
  or
  analysis_run
  or
  knowledge_crawl
  required
  What the task does.
- progress
  object
  required
  Steps of a task that splits its work into child jobs (one per conversation of a re-analysis). Zero steps: the task runs as one unit.
  
  failedSteps
  integer
  required
  minimum: 0
  finishedSteps
  integer
  required
  minimum: 0
  totalSteps
  integer
  required
  minimum: 0
- result
  object | null
  required
  What the task produced, by kind (for example the import counts). While an import runs, its progress (processedRows of totalRows); a cancelled import keeps the counts of what it did.
- retryable
  boolean
  required
  The task failed and retryTask can queue it again: its kind retries and it has attempts left.
- startedAt
  string | null
  required
  An instant in RFC 3339 format, in UTC.
  
  format: date-time
- status
  queued
  or
  running
  or
  completed
  or
  failed
  or
  cancelled
  required
- subjectId
  string | null
  required
  The resource the task acts on, when it has one.
}
error
null
required
metadata
object
required
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

401

UNAUTHORIZED: A valid access token is required.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

404

NOT_FOUND: The requested operation does not exist.
RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

405

HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

409

INVALID_STATE: The resource is not in a state that allows this operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

error
required
One of the following:
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
}