# Tasks API

**Base URL**: https://dev-cloud.acronis.com/api/task_manager/v2

## Security

### OAuth 2.0


Supported grant types:

* `client_credentials`
* `password`

Authorization URI example: `https://dev-cloud.acronis.com/api/2/idp/authorize`
Access token URI example: `https://dev-cloud.acronis.com/api/2/idp/token`

### Request parameters

#### Headers

| Name | Description |
|------|-------------|
| `Authorization`  | (Required) Used to send a valid OAuth 2 access token.<br><br>**Type**: String<br>**Pattern**: `^Bearer [0-9a-zA-Z\-\._~+/]*=$` |


### Responses

| Code | Description |
|------|-------------|
| `401`  | The request was denied due to an invalid or missing bearer access token. |
| `403`  | The request was denied due to the bearer access token having insufficient privileges. |

### Scopes

* `urn:acronis.com::task_manager::viewer`
* `urn:acronis.com::task_manager::issuer`
* `urn:acronis.com::task_manager::consumer`
* `urn:acronis.com::task_manager::admin`


## Endpoints

### GET /tasks

Fetches a list of tasks.

# Sustainable behavior (informative):
If `sustainable=true` and a task is returned to the queue, its sustainable activities are moved to `enqueued`
and must be restarted via `PUT /activities/{id}/started`. If not restarted by task completion, they will be marked `abandoned`.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::task_manager::admin`
* `urn:acronis.com::task_manager::viewer`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `lod` | (Optional) **Type**: String<br>**Allowed values**:<br>- `tiny`<br>- `short`<br>- `long`<br>- `full`<br>- `debug`<br>- `count` |
| `limit` | (Optional) A number of tasks to return in one page. This parameter restricts usage of the query string parameters to `after`.<br><br>**Type**: Integer |
| `after` | (Optional) The page token with the next page of the results. Can be used only with the `limit` query string parameter.<br><br>**Type**: String |
| `order` | (Optional) A position-dependent ordering filter.<br><br>Available ordering operators are:<br>- `asc(field)` - ascending order<br>- `desc(field)` - descending order<br><br>Where "field" is one of the following values:  `id`, `uuid`, `type`, `priority`,<br>`startedByUser`, `state`, `enqueuedAt`, `assignedAt`, `startedAt`, `updatedAt`, `completedAt`.<br><br>**Type**: String |
| `executorId` | (Optional) filter per task executor ID.<br><br>**Type**: String |
| `id` | (Optional) An ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `uuid` | (Optional) A UUID filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Pattern**: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` |
| `type` | (Optional) A type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `queue` | (Optional) Queue filter, multiple entries are accepted<br><br>**Type**: String |
| `priority` | (Optional) Priority filter, multiple entries are accepted<br><br>**Type**: String<br>**Allowed values**:<br>- `low`<br>- `belowNormal`<br>- `normal`<br>- `aboveNormal`<br>- `high` |
| `startedBy` | (Optional) Started by user filter, multiple entries are accepted, 'like' is supported in the form 'like(value)'<br><br>**Type**: String |
| `policyId` | (Optional) A policy ID filter. Multiple entries are accepted.<br><br>**Type**: String |
| `policyName` | (Optional) A policy name filter. Multiple entries are accepted.<br><br>The 'like' operator can be used to find a policy name by a sequence of characters. Usage: `like(value)` where "value" is a sequence of characters.<br><br>**Type**: String |
| `policyType` | (Optional) A policy type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `resourceId` | (Optional) A resource ID filter. Multiple entries are accepted.<br><br>**Type**: String |
| `resourceName` | (Optional) A resource name filter. Multiple entries are accepted.<br><br>The 'like' operator can be used to find a resource name by a sequence of characters. Usage: `like(value)` where "value" is a sequence of characters.<br><br>**Type**: String |
| `resourceType` | (Optional) A resource type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `workflowId` | (Optional) A workflow ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `state` | (Optional) A state filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Allowed values**:<br>- `enqueued`<br>- `assigned`<br>- `started`<br>- `paused`<br>- `completed` |
| `resultCode` | (Optional) A code filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Allowed values**:<br>- `ok`<br>- `error`<br>- `warning`<br>- `cancelled`<br>- `abandoned`<br>- `timedout` |
| `enqueuedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `assignedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `startedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `updatedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `completedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `tag` | (Optional) A tag filter. Multiple entries are accepted.<br><br>**Type**: String |
| `affinityAgentId` | (Optional) The ID of the agent that is bound to the task.<br><br>**Type**: String |
| `affinityClusterId` | (Optional) The ID of the cluster that is bound to the task.<br><br>**Type**: String |
| `allow_deleted` | (Optional) If true, allows to work with deleted entities.<br><br>**Type**: Boolean |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `400` | Bad user input. |
| `500` | Server error. |


### GET /tasks/{task-id}

Fetches a task by provided task ID.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::task_manager::admin`
* `urn:acronis.com::task_manager::viewer`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `lod` | (Optional) **Type**: String<br>**Allowed values**:<br>- `tiny`<br>- `short`<br>- `long`<br>- `full`<br>- `debug` |
| `allow_deleted` | (Optional) If true, allows to work with deleted entities.<br><br>**Type**: Boolean |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `404` | The task does not exist. |
| `400` | Bad user input. |
| `500` | Server error. |


### GET /activities

Fetches a list of activities.

# Sustainable behavior (informative):
Sustainable activities move to `enqueued` when their task is requeued and must be restarted with `PUT /activities/{id}/started`.
If not restarted by task completion, they will be marked `abandoned`.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::task_manager::admin`
* `urn:acronis.com::task_manager::viewer`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `lod` | (Optional) **Type**: String<br>**Allowed values**:<br>- `tiny`<br>- `short`<br>- `long`<br>- `full`<br>- `debug`<br>- `count` |
| `limit` | (Optional) A number of activities to return in one page. This parameter restricts usage of the query string parameters to `after`.<br><br>**Type**: Integer |
| `after` | (Optional) The page token with the next page of the results. Can be used only with the `limit` query string parameter.<br><br>**Type**: String |
| `order` | (Optional) An ordering filter (position-dependent).<br><br>Available ordering operators are:<br>- `asc(field)` - ascending order<br>- `desc(field)` - descending order<br><br>Where "field" is one of the following values:  `id`, `uuid`, `type`, `startedByUser`,<br>`state`, `createdAt`, `startedAt`, `updatedAt`, `completedAt`.<br><br>**Type**: String |
| `id` | (Optional) An ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `uuid` | (Optional) A UUID filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Pattern**: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` |
| `type` | (Optional) A type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `startedBy` | (Optional) A filter by a user who started the activity. Multiple entries are accepted.<br><br>The 'like' operator can be used to find a policy name by a sequence of characters. Usage: `like(value)` where "value" is a sequence of characters.<br><br>**Type**: String |
| `policyId` | (Optional) A policy ID filter. Multiple entries are accepted.<br><br>**Type**: String |
| `policyName` | (Optional) A policy name filter. Multiple entries are accepted.<br><br>The 'like' operator can be used to find a policy name by a sequence of characters. Usage: `like(value)` where "value" is a sequence of characters.<br><br>**Type**: String |
| `policyType` | (Optional) A policy type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `resourceId` | (Optional) A resource ID filter. Multiple entries are accepted.<br><br>**Type**: String |
| `resourceName` | (Optional) A resource name filter. Multiple entries are accepted.<br><br>The 'like' operator can be used to find a resource name by a sequence of characters. Usage: `like(value)` where "value" is a sequence of characters.<br><br>**Type**: String |
| `resourceType` | (Optional) A resource type filter. Multiple entries are accepted.<br><br>**Type**: String |
| `taskId` | (Optional) A task ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `workflowId` | (Optional) A workflow ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `parentActivityId` | (Optional) A parent activity ID filter. Multiple entries are accepted.<br><br>**Type**: Integer |
| `state` | (Optional) A state filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Allowed values**:<br>- `enqueued`<br>- `assigned`<br>- `started`<br>- `paused`<br>- `completed` |
| `resultCode` | (Optional) A code filter. Multiple entries are accepted.<br><br>**Type**: String<br>**Allowed values**:<br>- `ok`<br>- `error`<br>- `warning`<br>- `cancelled`<br>- `abandoned`<br>- `timedout` |
| `createdAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `startedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `updatedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `completedAt` | (Optional) A time filter. Single entry is accepted.<br><br>**Type**: String |
| `tag` | (Optional) A tag filter. Multiple entries are accepted.<br><br>**Type**: String |
| `sustainable` | (Optional) Filter by sustainable activities.<br><br>**Type**: Boolean |
| `allow_deleted` | (Optional) If true, allows to work with deleted entities.<br><br>**Type**: Boolean |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `400` | Bad user input. |
| `500` | Server error. |


### GET /activities/{activity-id}

Fetches an activity by provided activity ID.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::task_manager::admin`
* `urn:acronis.com::task_manager::viewer`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `lod` | (Optional) **Type**: String<br>**Allowed values**:<br>- `tiny`<br>- `short`<br>- `long`<br>- `full`<br>- `debug` |
| `allow_deleted` | (Optional) If true, allows to work with deleted entities.<br><br>**Type**: Boolean |


#### Responses

| Code | Description |
|------|-------------|
| `200` | - |
| `404` | The activity does not exist. |
| `400` | Bad user input. |
| `500` | Server error. |