# 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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://atoma.gitbook.io/atoma-docs/node-operators/atoma-node/atoma-node-daemon/task-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.