> For the complete documentation index, see [llms.txt](https://atoma.gitbook.io/atoma-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atoma.gitbook.io/atoma-docs/node-operators/atoma-node/atoma-node-daemon/task-subscriptions.md).

# Task subscriptions

## Task Subscription Management

**Subscribe to Task**

```
POST /task_subscribe
```

Submits a transaction to subscribe a node to a specific task.

**Request Body**

```json
{
    "task_small_id": 123,
    "node_badge_id": "0xab2..",
    "price_per_compute_unit": 10,
    "max_num_compute_units": 100,
    "gas": "0x789",
    "gas_budget": 1000,
    "gas_price": 10
}
```

**Request Fields**

* `task_small_id` (integer): ID of the task to subscribe to
* `node_small_id` (integer, optional): ID of the node to subscribe (if omitted, uses all registered nodes)
* `price_per_compute_unit` (integer): Price per compute unit the node will charge
* `max_num_compute_units` (integer): Maximum compute units the node will process per stack
* `gas` (string): Object ID of the gas object to pay for the transaction
* `gas_budget` (integer): Maximum gas units allowed for the transaction
* `gas_price` (integer): Price per gas unit in MIST

**Response Status Codes**

* `200 OK`: Successfully submitted task subscription transaction
* `500 Internal Server Error`: Failed to submit the transaction

**Response**

```json
{
    "tx_digest": "0xabc"
}
```

**Update Task Subscription** 

```
POST /task_update_subscription
```

Updates an already existing node subscription to a Task.

**Request Body:**

```json
{ 
    "task_small_id": 123, 
    "node_badge_id": "0xab2..", 
    "price_per_compute_unit": 15, 
    "max_num_compute_units": 150, 
    "gas": "0x789", // optional
    "gas_budget": 1000, // optional
    "gas_price": 10 // optional
}
```

**Request Fields**

* task\_small\_id (integer): ID of the task subscription to update
* node\_badge\_id (string): Object ID of the node badge
* price\_per\_compute\_unit (integer): New price per compute unit the node will charge
* max\_num\_compute\_units (integer): New maximum compute units the node will process per stack
* gas (string): Object ID of the gas object to pay for the transaction
* gas\_budget (integer): Maximum gas units allowed for the transaction
* gas\_price (integer): Price per gas unit in MIST

**Response Status Codes**

* 200 OK: Successfully submitted task subscription update transaction
* 500 Internal Server Error: Failed to submit the transaction

```json
Response

{
    "tx_digest": "0xabc"
}
```

**Unsubscribe from Task**

```
POST /task_unsubscribe
```

Submits a transaction to unsubscribe a node from a specific task.

**Request Body**

```json
{
    "task_small_id": 123,
    "node_badge_id": "0xab2..",
    "gas": "0x789",
    "gas_budget": 1000,
    "gas_price": 10
}
```

**Request Fields**

* `task_small_id` (integer): ID of the task to unsubscribe from
* `node_small_id` (integer, optional): ID of the node to unsubscribe (if omitted, uses all registered nodes)
* `gas` (string): Object ID of the gas object to pay for the transaction
* `gas_budget` (integer): Maximum gas units allowed for the transaction
* `gas_price` (integer): Price per gas unit in MIST

**Response Status Codes**

* `200 OK`: Successfully submitted task unsubscription transaction
* `500 Internal Server Error`: Failed to submit the transaction

**Response**

```json
{
    "tx_digest": "0xabc"
}
```

**Notes**

* A node must be registered before subscribing to tasks
* The `price_per_compute_unit` determines the node's compensation for processing requests
* The `max_num_compute_units` limits the size of stacks the node will accept
* Unsubscribing from a task:
  * Prevents the node from receiving new stacks for that task
  * Does not affect existing stack commitments
  * Can be reversed by subscribing again
* Both operations return a transaction digest for tracking the transaction status

**Example Error Responses**

```json
{
    "error": "Failed to submit node task subscription tx"
}
```

```json
{
    "error": "Failed to submit node task unsubscription tx"
}
```