> ## 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 Agents > Search agents in the workspace with operator-object filters. Returns paginated agents filtered by optional farm_id / status criteria. Omit body for an unfiltered first-page list. ## OpenAPI ````yaml /api-reference/openapi-legacy.json post /private-api/v1/{workspace_id}/agents/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}/agents/search: post: tags: - Agents summary: Search Agents description: >- Search agents in the workspace with operator-object filters. Returns paginated agents filtered by optional farm_id / status criteria. Omit body for an unfiltered first-page list. operationId: searchAgents parameters: - name: workspace_id required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentSearchRequestDto' responses: '200': description: Successfully retrieved agents 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: id: type: string description: Agent Id (uuid generated by nonce system) example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx farm_id: type: string description: Farm Id (uuid generated by nonce system) example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx farm: type: object properties: id: type: string description: Farm Id (uuid generated by nonce system) example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx name: description: Farm Name example: Farm Name type: - string - 'null' required: - id - name description: Farm details workspace_id: type: string description: Workspace Id example: org_xxxxxxxxxxxxxxxxxxxxxxxxxxx status: description: Status of the agent example: online/offline type: - string - 'null' last_updated_at: description: Timestamp of last updated. ISO Format example: '2025-08-27T00:00:00Z' type: - string - 'null' last_online_at: description: Timestamp of agent last online. ISO Format type: - string - 'null' version: description: Agent version example: v0.4.9-1-fdb7d5f type: - string - 'null' uptime: description: Agent uptime in seconds example: 6235631 type: - number - 'null' host: description: Agent host machine information example: platform: Darwin os: macOS-15.6-arm64-arm-64bit cpu_count: 12 uptime: 6235631 timestamp: 1761292878 load_average: - 2.0478515625 - 2.177734375 - 2.046875 memory: total: 34359738368 free: 64126976 used: 14793719808 swap_total: 2147483648 swap_free: 1095696384 swap_used: 1051787264 ip: 192.168.9.109 hostname: localhost additionalProperties: {} type: - object - 'null' required: - id - farm_id - farm - workspace_id - status - last_updated_at - last_online_at - version - uptime - host title: Agent 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: AgentSearchRequestDto: type: object properties: farm_id: description: >- Farm ID filter. Supports exact match (`eq`) or set membership (`in`). example: eq: 123e4567-e89b-12d3-a456-426614174000 type: object properties: eq: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ ne: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ nin: type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ additionalProperties: false status: description: Agent status filter example: eq: online type: object properties: eq: type: string ne: type: string in: type: array items: type: string nin: type: array items: type: string additionalProperties: false 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 ````