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

# Tasks

> Understanding tasks, task batches, and task parameters in Nonce

## Overview

Tasks are operations executed on miners. Nonce uses a Task Batch-based system where multiple tasks can be grouped and executed together.

### Task vs Task Batch

| Concept        | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| **Task**       | A single operation on one miner                                                   |
| **Task Batch** | A group of tasks created together, sharing the same task name and base parameters |

When you create tasks via the API, you always create a **Task Batch**. The system automatically creates individual tasks for each target miner.

***

## Task Names

Tasks are categorized by their target and purpose. A task batch creation payload includes:

```json theme={null}
{
  "task_name": "miner.power_mode.update",
  "miner_ids": ["miner-id-1", "miner-id-2"],
  "params": {
    "mode": "low"
  }
}
```

| Field       | Type      | Required    | Description                                                        |
| ----------- | --------- | ----------- | ------------------------------------------------------------------ |
| `task_name` | string    | Yes         | The task type to execute (see tables below)                        |
| `miner_ids` | string\[] | Conditional | Array of target miner IDs (required for miner-level tasks)         |
| `params`    | object    | No          | Task-specific parameters (see [Task Parameters](#task-parameters)) |

### Agent-Level Tasks

> `miner_ids` parameter is not required for agent-level tasks.

Operations that run on the agent software itself.

| Task Name           | Description                 |
| ------------------- | --------------------------- |
| `agent.scan.create` | Scan the network for miners |
| `agent.self.update` | Update the agent software   |

### Miner-Level Tasks

Operations that execute on individual miners.

> `miner_ids` parameter is required to specify target miners.

| Task Name                 | Description                                   |
| ------------------------- | --------------------------------------------- |
| `miner.system.reboot`     | Reboot the miner device                       |
| `miner.log.get`           | Collect diagnostic logs from the miner        |
| `miner.light.update`      | Toggle the miner's LED indicator light        |
| `miner.power_mode.update` | Change the [mining power mode](#mining-modes) |
| `miner.pool.update`       | Update mining pool configuration              |
| `miner.firmware.update`   | Update miner firmware                         |

### Miner Event Tasks

Special tasks that update miner asset metadata.

> `miner_ids` parameter is required to specify target miners.

| Task Name            | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `miner.asset.update` | Update miner asset status (e.g., mark as maintenance) |
| `miner.asset.delete` | Mark miner asset as deleted                           |

***

## Task Parameters

Each task type requires specific parameters.

### miner.system.reboot

Reboot a miner device.

| Parameter | Type    | Required | Description                                            |
| --------- | ------- | -------- | ------------------------------------------------------ |
| `force`   | boolean | No       | Force reboot even if miner is hashing (default: false) |

### miner.log.get

Collect diagnostic logs from a miner. No additional parameters required.

### miner.light.update

Toggle the miner's LED indicator light.

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `mode`    | string | Yes      | Light mode: `on` or `off` |

### miner.power\_mode.update

Change the mining power mode.

| Parameter | Type   | Required | Description                                           |
| --------- | ------ | -------- | ----------------------------------------------------- |
| `mode`    | string | Yes      | Mining mode (see [Mining Modes](#mining-modes) below) |

### miner.pool.update

Update mining pool configuration.

| Parameter      | Type   | Required | Description                                            |
| -------------- | ------ | -------- | ------------------------------------------------------ |
| `pools`        | array  | Yes      | Array of pool configurations                           |
| `pools[].url`  | string | Yes      | Pool URL (e.g., `stratum+tcp://pool.example.com:3333`) |
| `pools[].user` | string | Yes      | Pool username/worker name                              |

### miner.firmware.update

Update miner firmware.

| Parameter      | Type   | Required | Description                       |
| -------------- | ------ | -------- | --------------------------------- |
| `firmware_url` | string | Yes      | URL to download the firmware file |

### agent.scan.create

Scan the network for miners.

| Parameter  | Type   | Required | Description                               |
| ---------- | ------ | -------- | ----------------------------------------- |
| `ip_range` | string | No       | IP range to scan (e.g., `192.168.1.0/24`) |

### miner.asset.update

Update miner asset status.

| Parameter | Type   | Required | Description                                                                                              |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `status`  | string | Yes      | Available asset status: `online`, `on_rack`, `off_rack`, `transit`, `maintenance`, `retired`, `archived` |
| `comment` | string | No       | Optional comment for the asset status update                                                             |

### miner.asset.delete

Mark miner asset as deleted. No required parameters.

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `comment` | string | No       | Optional comment for the deletion |

***

## Task Status

Tasks progress through different statuses during their lifecycle.

| Status      | Description                                     |
| ----------- | ----------------------------------------------- |
| `created`   | Task has been created, waiting to be queued     |
| `queuing`   | Task is queued and waiting for agent to pick up |
| `pending`   | Task is being executed by the agent             |
| `succeed`   | Task completed successfully                     |
| `failed`    | Task execution failed                           |
| `timed_out` | Task execution exceeded the timeout limit       |
| `cancelled` | Task was cancelled before completion            |

### Task Lifecycle

```mermaid theme={null}
flowchart LR
    created([created]):::default --> queuing([queuing]):::default --> pending([pending]):::default --> succeed([succeed]):::success
    pending --> failed([failed]):::error
    pending --> timed_out([timed_out]):::error
    pending --> cancelled([cancelled]):::warning

    classDef default fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#374151
    classDef success fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#065f46
    classDef error fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b
    classDef warning fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
```

### Batch Status

Task batches have aggregated statuses based on their individual tasks.

| Batch Status      | Description                       |
| ----------------- | --------------------------------- |
| `pending`         | Some tasks are still running      |
| `succeed`         | All tasks completed successfully  |
| `failed`          | All tasks failed                  |
| `partial_succeed` | Some tasks succeeded, some failed |

***

## Mining Modes

Mining power modes vary by manufacturer. Not all modes are supported by all devices.

### Supported Modes by Manufacturer

| Manufacturer   | Supported Modes          |
| -------------- | ------------------------ |
| **AntMiner**   | `sleep`, `low`, `normal` |
| **WhatsMiner** | `low`, `normal`, `high`  |

> More manufacturers and modes may be added in future updates.

### Mode Descriptions

| Mode     | Power  | Description                                                |
| -------- | ------ | ---------------------------------------------------------- |
| `sleep`  | \~5%   | Standby mode, minimal power consumption (AntMiner only)    |
| `low`    | \~75%  | Reduced hashrate, energy efficient                         |
| `normal` | \~100% | Standard operation, balanced performance                   |
| `high`   | \~125% | Maximum hashrate, high power consumption (WhatsMiner only) |

<Warning>
  Attempting to set an unsupported mode for a miner's manufacturer will result in a validation error.
</Warning>

***

## Example: Creating a Task Batch

```bash theme={null}
curl -X POST "https://api.nonce.app/private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_name": "miner.power_mode.update",
    "miner_ids": ["miner-id-1", "miner-id-2"],
    "params": {
      "mode": "low"
    }
  }'
```

This creates a task batch that will change the mining mode to `low` for the specified miners.

### Response Format

The API response includes a `meta` field with task creation summary.

<Note>
  The `meta` field provides informational hints to help you understand what happened during task creation. It indicates which tasks were actually created and which were skipped, along with the reasons. This is particularly useful for debugging and understanding why certain miners didn't receive tasks.
</Note>

```json theme={null}
{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "summary": {
      "created_count": 1,
      "skipped_count": 1
    },
    "skipped": [
      {
        "reason": "no_change",
        "message": "Task skipped: miner already in requested mode",
        "miner_ids": ["miner-id-2"]
      }
    ]
  }
}
```

#### Meta Summary

| Field           | Type   | Description                          |
| --------------- | ------ | ------------------------------------ |
| `created_count` | number | Number of tasks successfully created |
| `skipped_count` | number | Number of tasks skipped              |

#### Skipped Reasons

When some miners are skipped, the `skipped` array provides details:

| Field       | Type      | Description                        |
| ----------- | --------- | ---------------------------------- |
| `reason`    | string    | Skip reason code (see table below) |
| `message`   | string    | Human-readable explanation         |
| `miner_ids` | string\[] | Array of affected miner IDs        |

| Reason             | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `no_change`        | Miner is already in the requested state                         |
| `unsupported_mode` | The requested mode is not supported by the miner's manufacturer |
| `miner_not_found`  | Miner ID does not exist or is not accessible                    |