Overview
Tasks are operations executed on miners. Nonce uses a batch-based task 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 |
Task Names
Tasks are categorized by their target and purpose. A task batch creation payload includes:
{
"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) |
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 |
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 |
|---|
action | 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 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
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) |
Attempting to set an unsupported mode for a miner’s manufacturer will result in a validation error.
Example: Creating a Task Batch
curl -X POST "https://api.nonce.app/private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches" \
-H "x-api-key: {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"
}
}'
low for the specified miners.
The API response includes a meta field with task creation summary.
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.
{
"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"]
}
]
}
}
| 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 |
