Skip to main content
A task is one operation on one miner or Agent, or one change to a miner record. You don’t create tasks one at a time: each create operation produces a task batch, and Nonce generates one task for each target. This page covers the create operations, their parameters, the response, and the statuses you use to track the work.

Tasks and task batches

The two terms name different levels of the same request.

Operation impact and permissions

Tasks cover operations with different impact and permission requirements. To create a task batch, your role must have the required operation permission, and the target farm must be within your assigned scope. See the permissions by role for the operations available to each role.

Create a task batch

Each operation has its own path under a farm’s /task-batches. The path selects the operation, so the request body has no task_name.
The create operations are in Beta. Their requests and responses may change in incompatible ways. See Versions and stability.
The following request turns on the indicator light of two miners:
The request body has up to two fields: When you migrate from v1, see the endpoint and field mappings.

Miner operations

These operations run on the miners you list in miner_ids. The task_name column is the value that task batch responses and the task_name filter of ListTaskBatches use for the operation. The task name miner.pool.update updates mining pool configuration. No API operation creates it.

Miner record operations

These operations change the inventory records of the miners in miner_ids. They don’t send anything to the devices.

Agent operations

These operations run on the Agents in the farm, so the request has no miner_ids.

Operation parameters

The tables below list what each operation accepts in params. For the complete request and response schema, open the operation in the API Reference.

CreateRebootTaskBatch

params is optional.

CreateLogGetTaskBatch

This operation takes no params. Send miner_ids only.

CreateLightUpdateTaskBatch

CreateMiningModeUpdateTaskBatch

CreatePoolLockTaskBatch

A pool lock uses an auth package to pin the pool configuration, which prevents unauthorized pool changes while the lock is in place.

CreateFirmwareUpdateTaskBatch

CreateTagsUpdateTaskBatch

Tags are metadata only, so this operation doesn’t affect mining. params is required, and you can send add, remove, or both.

CreateRecordDeleteTaskBatch

Use this operation after you physically decommission miners. params is optional.
Deleting a miner record also clears its rack position. A deleted miner that is still online reappears after its next successful report, without a rack position.

CreateAgentScanTaskBatch

params is required, but it can be an empty object.

CreateAgentIpDiagnosisTaskBatch

params is required, but it can be an empty object.

CreateAgentSelfUpdateTaskBatch

params is required, but it can be an empty object.

CreateAgentPauseTaskBatch and CreateAgentResumeTaskBatch

Both operations take an empty JSON object as the request body. Paused Agents keep scanning, collecting miner data, and sending heartbeats, so they report current data as soon as they resume. While any Agent in the farm is paused, you can create only pause, resume, self-update, and scan task batches in that farm. Other create operations are rejected with VALIDATION_ERROR.
Pause and resume require every Agent in the farm to be online. If any Agent is offline, the API returns AGENT_OFFLINE and creates no task batch.

Read the response

A create operation returns the task batches it created, a summary, and the miners it skipped:
Keep the id of each batch in data.batches: you need it to track the task batch. For the created_by object, see Actors.

Summary

data.summary counts miners, not tasks.

Skipped miners

data.skipped groups the skipped miners by reason. Each entry has these fields: A miner is skipped for one of these reasons:

Track a task batch

After you create a task batch, call GetTaskBatch for its aggregate status and per-status task counts, and ListTaskBatchTasks for each task’s status, timestamps, result, and error. ListTaskBatchTasks takes a status filter, and each task from a log collection carries a signed log_download_url.

Task status

Each task moves through these statuses: A task ends in one of four statuses:
A task moves from created to queuing to pending, then ends as succeed, failed, timed_out, or cancelled.Task lifecycle

Task batch status

A task batch’s status aggregates the statuses of its tasks:

Mining modes

mining_mode accepts one of the four general modes below, or a model-specific preset name of up to 36 characters, such as 5600W. Not every device supports every mode. The supported modes depend on the manufacturer: If you request a mode that a miner’s manufacturer doesn’t support, the request fails with a validation error.

See also