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.
When you migrate from v1, see the endpoint and field mappings.
Miner operations
These operations run on the miners you list inminer_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 inminer_ids. They don’t send anything to the devices.
Agent operations
These operations run on the Agents in the farm, so the request has nominer_ids.
Operation parameters
The tables below list what each operation accepts inparams. For the complete request and response schema, open the operation in the API Reference.
CreateRebootTaskBatch
params is optional.
CreateLogGetTaskBatch
This operation takes noparams. 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 withVALIDATION_ERROR.
Read the response
A create operation returns the task batches it created, a summary, and the miners it skipped: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, callGetTaskBatch 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:
Task batch status
A task batch’sstatus 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
- Actors: read
created_byto see who created a task batch - Requests and responses: the response envelope, pagination, and error format
- Available tools: the same operations as MCP tools