Tasks

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:

{
  "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.ip_diagnosis.create`	Run IP diagnosis and upload a CSV report
`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.pool.lock`	Lock or unlock miner pool configuration
`miner.firmware.update`	Update miner firmware

Miner Event Tasks

Special tasks that update miner inventory metadata.

miner_ids parameter is required to specify target miners.

Task Name	Description
`miner.tags.update`	Add or remove operator-managed tags on miners
`miner.record.delete`	Mark miners as deleted in inventory
`miner.rack_location.update`	Update miner rack and position metadata

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 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.pool.lock

Lock or unlock miner pool configuration via auth package. Prevents unauthorized pool changes while locked.

Parameter	Type	Required	Description
`firmware_url`	string	Yes	URL to the auth package file
`action`	string	Yes	`lock` pins the enforced pool configuration; `unlock` restores configurable pools

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`)

agent.ip_diagnosis.create

Run agent IP diagnosis and upload a CSV report.

Parameter	Type	Required	Description
`target_scope`	string	No	Diagnosis target scope (default: `known_with_custom`)
`custom_targets`	array	No	Custom diagnosis targets
`ping_only`	boolean	No	Only perform ICMP ping checks for targets without local context

miner.tags.update

Add or remove operator-managed tags on miners. Metadata-only; does not affect mining operation.

Parameter	Type	Required	Description
`add`	string[]	No	Tags to add to every selected miner (up to 50 tags per miner)
`remove`	string[]	No	Tags to remove from every selected miner

miner.record.delete

Mark miners as deleted in inventory. Use after physical decommission.

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

miner.rack_location.update

Update miner rack and position metadata. Uses a top-level updates array instead of miner_ids + params.

Field	Type	Required	Description
`updates[].miner_id`	string	Yes	Target miner ID
`updates[].rack`	string \| null	Yes	Rack identifier (up to 50 chars); `null` to clear
`updates[].position`	number \| null	Yes	Slot position within the rack; `null` to clear

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 "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.

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"]
      }
    ]
  }
}

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

Get started

Concepts

MCP

API Reference

Overview

Task vs Task Batch

Task Names

Agent-Level Tasks

Miner-Level Tasks

Miner Event Tasks

Task Parameters

miner.system.reboot

miner.log.get

miner.light.update

miner.power_mode.update

miner.pool.update

miner.pool.lock

miner.firmware.update

agent.scan.create

agent.ip_diagnosis.create

miner.tags.update

miner.record.delete

miner.rack_location.update

Task Status

Task Lifecycle

Batch Status

Mining Modes

Supported Modes by Manufacturer

Mode Descriptions

Example: Creating a Task Batch

Response Format

Meta Summary

Skipped Reasons

​Overview

​Task vs Task Batch

​Task Names

​Agent-Level Tasks

​Miner-Level Tasks

​Miner Event Tasks

​Task Parameters

​miner.system.reboot

​miner.log.get

​miner.light.update

​miner.power_mode.update

​miner.pool.update

​miner.pool.lock

​miner.firmware.update

​agent.scan.create

​agent.ip_diagnosis.create

​miner.tags.update

​miner.record.delete

​miner.rack_location.update

​Task Status

​Task Lifecycle

​Batch Status

​Mining Modes

​Supported Modes by Manufacturer

​Mode Descriptions

​Example: Creating a Task Batch

​Response Format

​Meta Summary

​Skipped Reasons

Overview

Task vs Task Batch

Task Names

Agent-Level Tasks

Miner-Level Tasks

Miner Event Tasks

Task Parameters

miner.system.reboot

miner.log.get

miner.light.update

miner.power_mode.update

miner.pool.update

miner.pool.lock

miner.firmware.update

agent.scan.create

agent.ip_diagnosis.create

miner.tags.update

miner.record.delete

miner.rack_location.update

Task Status

Task Lifecycle

Batch Status

Mining Modes

Supported Modes by Manufacturer

Mode Descriptions

Example: Creating a Task Batch

Response Format

Meta Summary

Skipped Reasons