> ## 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. # Search Task Batches > Search task batches in the farm with operator-object filters. Supports status, task_name, actor_type, and created_at criteria. Omit body for an unfiltered first-page list. Automation-created batches include metadata.filterSummary with per-stage filter counts (total, passed, skippedUptime, skippedAnomaly, skippedNonNormal, skippedRebootLimit, skippedTemperature, temperatureBypassedZeroHashrate) — useful for diagnosing why automation filtered out miners. ## OpenAPI ````yaml /api-reference/openapi-legacy.json post /private-api/v1/{workspace_id}/farms/{farm_id}/tasks/search openapi: 3.1.0 info: title: Nonce Private API description: |- Nonce Private API documentation - Internal endpoints for system integration Generated by NestJS Swagger Module with nestjs-zod Scope: Private API endpoints only (/private-api/*) Do not edit this file manually - regenerate with: pnpm run docs:openapi version: 1.0.0 contact: {} servers: - url: https://api.nonce.app description: Production server security: [] tags: [] paths: /private-api/v1/{workspace_id}/farms/{farm_id}/tasks/search: post: tags: - Tasks summary: Search Task Batches description: >- Search task batches in the farm with operator-object filters. Supports status, task_name, actor_type, and created_at criteria. Omit body for an unfiltered first-page list. Automation-created batches include metadata.filterSummary with per-stage filter counts (total, passed, skippedUptime, skippedAnomaly, skippedNonNormal, skippedRebootLimit, skippedTemperature, temperatureBypassedZeroHashrate) — useful for diagnosing why automation filtered out miners. operationId: searchTaskBatches parameters: - name: workspace_id required: true in: path schema: type: string - name: farm_id required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskSearchRequestDto' responses: '200': description: Successfully retrieved task batches content: application/json: schema: type: object properties: success: type: boolean example: true description: Indicates if the request was successful data: type: array description: Array of items items: type: object properties: batch_id: type: string description: Miner task batch ID example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx task_name: type: string description: Miner task name example: miner.log.get enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.tags.update - miner.record.delete - miner.rack_location.update status: type: string enum: - pending - succeed - failed - partial_succeed description: >- Aggregate status of a task batch. `pending` = at least one task is still running; `succeed` = all tasks succeeded; `failed` = all tasks failed, timed out, or were cancelled; `partial_succeed` = finished with a mix of success and failure. example: pending task_count: type: number description: Number of tasks in the batch example: 10 succeed_count: type: number description: Number of succeeded tasks example: 8 failed_count: type: number description: Number of failed tasks example: 2 task_params: description: >- Task parameters (JSON). Structure varies by task_name. additionalProperties: {} type: - object - 'null' metadata: description: >- Automation trigger context. Keys: trigger ({predicateField, predicateValue}), automation ({id, name}), filterSummary ({total, passed, skippedUptime?, skippedAnomaly?, skippedNonNormal?, skippedRebootLimit?, skippedTemperature?, temperatureBypassedZeroHashrate?}). filterSummary shows how many miners were evaluated vs filtered at each stage — use it to identify automation filtering bottlenecks. Null for manually created batches. additionalProperties: {} type: - object - 'null' created_by: description: >- Represents an entity that performs actions in the system (user, API key, or system) properties: type: type: string enum: - user - apikey - system description: The type of actor example: user id: type: string description: The unique identifier of the actor example: user_2xGz1234567890 name: description: The display name of the actor example: John Doe type: - string - 'null' avatar: description: The avatar URL of the actor example: https://example.com/avatar.png type: - string - 'null' metadata: description: Additional metadata about the actor type: object additionalProperties: {} required: - type - id - name - avatar title: Actor type: - object - 'null' created_at: type: string format: date-time example: '2025-09-07T00:00:00Z' description: >- This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. required: - batch_id - task_name - status - task_count - succeed_count - failed_count - task_params - created_by - created_at title: Task Batch Summary pagination: type: object description: Pagination metadata properties: total: type: number example: 50 description: Total number of items limit: type: number example: 10 description: Maximum number of items per page offset: type: number example: 0 description: Number of items to skip hasNext: type: boolean example: true description: Whether there are more items after this page hasPrevious: type: boolean example: false description: Whether there are items before this page required: - total - limit - offset - hasNext - hasPrevious error: type: 'null' example: null description: Error object (null on success) required: - success - data - pagination - error '400': description: Bad Request - Invalid parameters content: application/json: schema: type: object properties: success: type: boolean enum: - false data: type: 'null' example: null error: type: object properties: code: type: string message: type: string details: type: object properties: field_errors: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false additionalProperties: {} traceId: type: string required: - code - message additionalProperties: false required: - success - data - error additionalProperties: false example: success: false data: null error: code: VALIDATION_ERROR message: Validation failed '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: success: type: boolean enum: - false data: type: 'null' example: null error: type: object properties: code: type: string message: type: string details: type: object properties: field_errors: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false additionalProperties: {} traceId: type: string required: - code - message additionalProperties: false required: - success - data - error additionalProperties: false example: success: false data: null error: code: UNAUTHORIZED message: Invalid or missing API key '403': description: Forbidden - Valid API key but insufficient permissions content: application/json: schema: type: object properties: success: type: boolean enum: - false data: type: 'null' example: null error: type: object properties: code: type: string message: type: string details: type: object properties: field_errors: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false additionalProperties: {} traceId: type: string required: - code - message additionalProperties: false required: - success - data - error additionalProperties: false example: success: false data: null error: code: FORBIDDEN message: Access denied to workspace '500': description: Internal Server Error content: application/json: schema: type: object properties: success: type: boolean enum: - false data: type: 'null' example: null error: type: object properties: code: type: string message: type: string details: type: object properties: field_errors: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false additionalProperties: {} traceId: type: string required: - code - message additionalProperties: false required: - success - data - error additionalProperties: false example: success: false data: null error: code: INTERNAL_SERVER_ERROR message: Internal server error security: - clerk-api-key: [] components: schemas: TaskSearchRequestDto: type: object properties: status: description: Aggregate task batch status filter example: in: - failed - partial_succeed type: object properties: eq: type: string enum: - pending - succeed - failed - partial_succeed description: >- Aggregate status of a task batch. `pending` = at least one task is still running; `succeed` = all tasks succeeded; `failed` = all tasks failed, timed out, or were cancelled; `partial_succeed` = finished with a mix of success and failure. example: succeed ne: type: string enum: - pending - succeed - failed - partial_succeed description: >- Aggregate status of a task batch. `pending` = at least one task is still running; `succeed` = all tasks succeeded; `failed` = all tasks failed, timed out, or were cancelled; `partial_succeed` = finished with a mix of success and failure. example: succeed in: type: array items: type: string enum: - pending - succeed - failed - partial_succeed description: >- Aggregate status of a task batch. `pending` = at least one task is still running; `succeed` = all tasks succeeded; `failed` = all tasks failed, timed out, or were cancelled; `partial_succeed` = finished with a mix of success and failure. example: succeed nin: type: array items: type: string enum: - pending - succeed - failed - partial_succeed description: >- Aggregate status of a task batch. `pending` = at least one task is still running; `succeed` = all tasks succeeded; `failed` = all tasks failed, timed out, or were cancelled; `partial_succeed` = finished with a mix of success and failure. example: succeed additionalProperties: false task_name: description: Task name filter example: in: - miner.system.reboot - miner.log.get type: object properties: eq: type: string enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.tags.update - miner.record.delete - miner.rack_location.update description: >- Task or event type dispatched to miners or agents. Execution types: `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`, `agent.self.update`. Event types: `miner.tags.update`, `miner.record.delete`, `miner.rack_location.update`. example: miner.system.reboot ne: type: string enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.tags.update - miner.record.delete - miner.rack_location.update description: >- Task or event type dispatched to miners or agents. Execution types: `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`, `agent.self.update`. Event types: `miner.tags.update`, `miner.record.delete`, `miner.rack_location.update`. example: miner.system.reboot in: type: array items: type: string enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.tags.update - miner.record.delete - miner.rack_location.update description: >- Task or event type dispatched to miners or agents. Execution types: `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`, `agent.self.update`. Event types: `miner.tags.update`, `miner.record.delete`, `miner.rack_location.update`. example: miner.system.reboot nin: type: array items: type: string enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.tags.update - miner.record.delete - miner.rack_location.update description: >- Task or event type dispatched to miners or agents. Execution types: `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`, `agent.self.update`. Event types: `miner.tags.update`, `miner.record.delete`, `miner.rack_location.update`. example: miner.system.reboot additionalProperties: false actor_type: type: object properties: eq: type: string enum: - user - automation - api description: >- Actor type used to filter task batches by creator. `user` = batches created by human users through the Nonce app; `automation` = batches created by the Automation workflow system; `api` = batches created via private-api or connect-api tokens. example: user additionalProperties: false description: >- Actor type filter. Only `eq` operator supported; multi-type filtering is not available. example: eq: user created_at: type: object properties: eq: type: string gt: type: string gte: type: string lt: type: string lte: type: string additionalProperties: false description: >- Date filter operators using ISO 8601 UTC strings. Provide at least one operator. example: gte: '2026-04-01T00:00:00Z' page: description: Page number, starting at 1 example: 1 type: integer minimum: 1 maximum: 9007199254740991 limit: description: Results per page example: 50 type: integer minimum: 1 maximum: 10000 securitySchemes: clerk-api-key: scheme: bearer bearerFormat: API Key type: http description: Clerk Machine API Key for authentication ````