---
title: "Cancel a task"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel a task

Path: SURA API › Operation tasks

`POST /v1/sura/operation-tasks/{taskId}/cancel`

Cancel a task you started that has not started running; one that has runs to its end.

- **Scopes:** any one of `sura:appointments:read`, `sura:appointments:write`, `sura:affiliations:read`
- **Credentials:** an API key, a client-credentials token or a person's access token
- **Effect:** writes
- **Limits:** request body up to 32 KB, response up to 256 KB
- **CLI:** `arbol sura operation-tasks cancel` · not available on MCP

## Authentication

Requires one of the following:

- `arbolHuman`, oauth2, scopes: `sura:appointments:read`
- `arbolHuman`, oauth2, scopes: `sura:appointments:write`
- `arbolHuman`, oauth2, scopes: `sura:affiliations:read`
- `arbolMachine`, oauth2, scopes: `sura:appointments:read`
- `arbolMachine`, oauth2, scopes: `sura:appointments:write`
- `arbolMachine`, oauth2, scopes: `sura:affiliations:read`
- `arbolApiKey`, http, header `Authorization`

## Path parameters

- `taskId` (`sura.operationTasks.cancel.path.taskId`; string, required) — The task id.
  - minLength 1; maxLength 200

## Request body

_Required._

## Example request

```json
{}
```

## Code samples

### cURL

```bash
curl "https://api.getarbol.com/v1/sura/operation-tasks/<taskId>/cancel" \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

### TypeScript

```typescript
import { createClient } from "@arbol-ai/sdk";

const arbol = createClient({
  baseUrl: "https://api.getarbol.com",
  token: process.env.ARBOL_API_KEY!,
});

const { data } = await arbol.sura.operationTasks.cancel({
  taskId: "<taskId>",
  body: {},
});
```

### Rust

```rust
use arbol_sdk::{types, Client, Credential};

let arbol = Client::new(Credential::ApiKey(std::env::var("ARBOL_API_KEY")?))?;

let data = arbol
    .sura()
    .operation_tasks()
    .cancel(&types::SuraOperationTasksCancelInput {
        task_id: "<taskId>".into(),
    })
    .await?;
```

### CLI

```bash
arbol sura operation-tasks cancel '<taskId>'
```

## Responses

### 200

Successful operation.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.200.success`; boolean, required)
  - one of `true`
- `data` (`sura.operationTasks.cancel.response.200.data`; object, required) — A call that goes on after it was answered.
  - `taskId` (`sura.operationTasks.cancel.response.200.data.taskId`; string, required)
  - `status` (`sura.operationTasks.cancel.response.200.data.status`; string, required)
    - one of `"working"`, `"completed"`, `"failed"`, `"cancelled"`
  - `createdAt` (`sura.operationTasks.cancel.response.200.data.createdAt`; string, required)
    - format `date-time`
  - `lastUpdatedAt` (`sura.operationTasks.cancel.response.200.data.lastUpdatedAt`; string, required)
    - format `date-time`
  - `ttlMs` (`sura.operationTasks.cancel.response.200.data.ttlMs`; integer, required)
  - `pollIntervalMs` (`sura.operationTasks.cancel.response.200.data.pollIntervalMs`; integer, required)
  - `result` (`sura.operationTasks.cancel.response.200.data.result`; unknown, optional) — The operation's value, once completed.
  - `error` (`sura.operationTasks.cancel.response.200.data.error`; object, optional) — The operation's failure, once failed.
    - `code` (`sura.operationTasks.cancel.response.200.data.error.code`; string, required) — The failure code, stable across releases.
    - `message` (`sura.operationTasks.cancel.response.200.data.error.message`; string, required) — What went wrong, for people; it never contains input values.
    - `retryable` (`sura.operationTasks.cancel.response.200.data.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - `data` (`sura.operationTasks.cancel.response.200.data.error.data`; object, required) — Diagnostics the code declares; empty for most codes.
- `error` (`sura.operationTasks.cancel.response.200.error`; unknown, required)
- `metadata` (`sura.operationTasks.cancel.response.200.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.200.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": true,
  "data": {
    "taskId": "string",
    "status": "working",
    "createdAt": "2019-08-24T14:15:22Z",
    "lastUpdatedAt": "2019-08-24T14:15:22Z",
    "ttlMs": 0,
    "pollIntervalMs": 0,
    "result": null,
    "error": {
      "code": "string",
      "message": "string",
      "retryable": true,
      "data": {}
    }
  },
  "error": null,
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 400

`INVALID_INPUT`: The request does not match the published schema.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.400.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.400.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.400.error`; object, required) — The request does not match the published schema.
  - `code` (`sura.operationTasks.cancel.response.400.error.code`; string, required) — The failure code, stable across releases.
    - one of `"INVALID_INPUT"`
  - `message` (`sura.operationTasks.cancel.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.400.error.data`; object, required)
    - `issues` (`sura.operationTasks.cancel.response.400.error.data.issues`; array<object>, optional)
      - `path` (`sura.operationTasks.cancel.response.400.error.data.issues.path`; string, required) — RFC 6901 JSON Pointer to the refused field; empty for the whole input.
        - maxLength 256
      - `message` (`sura.operationTasks.cancel.response.400.error.data.issues.message`; string, required)
        - maxLength 256
- `metadata` (`sura.operationTasks.cancel.response.400.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.400.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_INPUT",
    "message": "string",
    "retryable": false,
    "data": {
      "issues": [
        {
          "path": "string",
          "message": "string"
        }
      ]
    }
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 401

`UNAUTHORIZED`: A valid access token is required.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.401.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.401.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.401.error`; object, required) — A valid access token is required.
  - `code` (`sura.operationTasks.cancel.response.401.error.code`; string, required) — The failure code, stable across releases.
    - one of `"UNAUTHORIZED"`
  - `message` (`sura.operationTasks.cancel.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.401.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.401.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.401.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 403

`FORBIDDEN`: The token does not authorize this operation.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.403.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.403.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.403.error`; object, required) — The token does not authorize this operation.
  - `code` (`sura.operationTasks.cancel.response.403.error.code`; string, required) — The failure code, stable across releases.
    - one of `"FORBIDDEN"`
  - `message` (`sura.operationTasks.cancel.response.403.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.403.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.403.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.403.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.403.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 413

`REQUEST_TOO_LARGE`: The request exceeds the allowed size.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.413.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.413.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.413.error`; object, required) — The request exceeds the allowed size.
  - `code` (`sura.operationTasks.cancel.response.413.error.code`; string, required) — The failure code, stable across releases.
    - one of `"REQUEST_TOO_LARGE"`
  - `message` (`sura.operationTasks.cancel.response.413.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.413.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.413.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.413.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.413.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "REQUEST_TOO_LARGE",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 415

`UNSUPPORTED_MEDIA_TYPE`: The request content type is not supported.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.415.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.415.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.415.error`; object, required) — The request content type is not supported.
  - `code` (`sura.operationTasks.cancel.response.415.error.code`; string, required) — The failure code, stable across releases.
    - one of `"UNSUPPORTED_MEDIA_TYPE"`
  - `message` (`sura.operationTasks.cancel.response.415.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.415.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.415.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.415.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.415.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 429

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

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.429.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.429.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.429.error`; object, required) — The request rate limit was exceeded. Try again later.
  - `code` (`sura.operationTasks.cancel.response.429.error.code`; string, required) — The failure code, stable across releases.
    - one of `"RATE_LIMITED"`
  - `message` (`sura.operationTasks.cancel.response.429.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.429.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `true`
  - `data` (`sura.operationTasks.cancel.response.429.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.429.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.429.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMITED",
    "message": "string",
    "retryable": true,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 500

`INTERNAL_ERROR`: The service could not complete the operation.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.500.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.500.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.500.error`; object, required) — The service could not complete the operation.
  - `code` (`sura.operationTasks.cancel.response.500.error.code`; string, required) — The failure code, stable across releases.
    - one of `"INTERNAL_ERROR"`
  - `message` (`sura.operationTasks.cancel.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.500.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.500.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.500.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 502

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

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.502.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.502.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.502.error`; object, required) — The operation may have been applied; check its result before repeating it.
  - `code` (`sura.operationTasks.cancel.response.502.error.code`; string, required) — The failure code, stable across releases.
    - one of `"OUTCOME_UNKNOWN"`
  - `message` (`sura.operationTasks.cancel.response.502.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.502.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `false`
  - `data` (`sura.operationTasks.cancel.response.502.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.502.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.502.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "OUTCOME_UNKNOWN",
    "message": "string",
    "retryable": false,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 503

`UPSTREAM_UNAVAILABLE`: The upstream service could not complete the request.

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.503.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.503.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.503.error`; object, required) — The upstream service could not complete the request.
  - `code` (`sura.operationTasks.cancel.response.503.error.code`; string, required) — The failure code, stable across releases.
    - one of `"UPSTREAM_UNAVAILABLE"`
  - `message` (`sura.operationTasks.cancel.response.503.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.503.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `true`
  - `data` (`sura.operationTasks.cancel.response.503.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.503.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.503.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UPSTREAM_UNAVAILABLE",
    "message": "string",
    "retryable": true,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```

### 504

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

#### Body (application/json)

- `success` (`sura.operationTasks.cancel.response.504.success`; boolean, required)
  - one of `false`
- `data` (`sura.operationTasks.cancel.response.504.data`; unknown, required)
- `error` (`sura.operationTasks.cancel.response.504.error`; object, required) — The upstream service did not respond before its deadline.
  - `code` (`sura.operationTasks.cancel.response.504.error.code`; string, required) — The failure code, stable across releases.
    - one of `"UPSTREAM_TIMEOUT"`
  - `message` (`sura.operationTasks.cancel.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values.
  - `retryable` (`sura.operationTasks.cancel.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed.
    - one of `true`
  - `data` (`sura.operationTasks.cancel.response.504.error.data`; object, required) — No fields.
- `metadata` (`sura.operationTasks.cancel.response.504.metadata`; object, required) — What every answer carries besides its data or error.
  - `requestId` (`sura.operationTasks.cancel.response.504.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id.

##### Example

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "string",
    "retryable": true,
    "data": {}
  },
  "metadata": {
    "requestId": "string"
  }
}
```

#### Body (text/plain)

##### Example

```text
string
```


Source: https://docs.getarbol.com/api/sura/operation-tasks/cancel/index.md
