> ## 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. ## OpenAPI ````yaml /api-reference/openapi.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: - Private API - Task 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. 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.asset.update - miner.asset.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, skippedNonNormal?, skippedAnomaly?, skippedTemperature?}). 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: datetime example: YYYY-MM-DDTHH:MM:SSZ 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: statusCode: type: number description: HTTP status code example: 400 message: type: string description: Error message example: Invalid request parameters error: type: string description: Error type example: Bad Request required: - statusCode - message - error '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 401 message: type: string description: Error message example: Invalid or missing API key error: type: string description: Error type example: Unauthorized required: - statusCode - message - error '403': description: Forbidden - Valid API key but insufficient permissions content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 403 message: type: string description: Error message example: Access denied to workspace error: type: string description: Error type example: Forbidden required: - statusCode - message - error security: - clerk-api-key: [] components: schemas: TaskSearchRequestDto: type: object properties: status: 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 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 additionalProperties: false description: Enum or ID filter operators. Provide at least one operator. example: in: - online - offline task_name: 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.asset.update - miner.asset.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.asset.update`, `miner.asset.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.asset.update - miner.asset.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.asset.update`, `miner.asset.delete`, `miner.rack_location.update`. example: miner.system.reboot additionalProperties: false description: Enum or ID filter operators. Provide at least one operator. example: in: - online - offline 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: type: integer minimum: 1 maximum: 9007199254740991 limit: type: integer minimum: 1 maximum: 10000 securitySchemes: clerk-api-key: scheme: bearer bearerFormat: API Key type: http description: Clerk Machine API Key for authentication ````