> ## 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. # List Granted Miners > Returns miners from a farm shared with the caller through a cross-organization grant. The grant must include the requested farm. ## OpenAPI ````yaml /api-reference/openapi-legacy.json get /private-api/v1/granted/{workspace_id}/farms/{farm_id}/miners/latest 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/granted/{workspace_id}/farms/{farm_id}/miners/latest: get: tags: - Miners summary: List Granted Miners description: >- Returns miners from a farm shared with the caller through a cross-organization grant. The grant must include the requested farm. operationId: listGrantedMiners parameters: - name: workspace_id required: true in: path schema: type: string - name: farm_id required: true in: path schema: type: string - name: page required: false in: query description: 'Page number (default: 1)' schema: minimum: 1 example: 1 type: number - name: pageSize required: false in: query description: 'Number of items per page (default: 10, max: 10000)' schema: minimum: 1 maximum: 10000 example: 10 type: number - name: agent_id required: false in: query description: Agent Id (uuid generated by nonce system) schema: example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 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)$ - name: sn required: false in: query description: >- Miner, hashboard, power supply, or controller serial number (single value) schema: example: HTM3FS28HD25011939878367054H36045 type: string minLength: 1 - name: mac required: false in: query description: Filter miners by MAC address schema: example: AA:BB:CC:DD:EE:FF type: string minLength: 1 - name: status required: false in: query description: >- Filter miners by status. Accepts both run status (`online`, `stale`) and preset tags (`archived`, `maintenance`, `retired`, `off_rack`, `transit`). Run status and tags are independent axes — filtering by `online` does NOT exclude miners carrying tags. For new clients prefer `tags` for tag filtering and `status` for connectivity-state filtering. Supports multiple values separated by `,` (e.g., "online,stale") or multiple query parameters (e.g., "status=online&status=stale"). Available statuses: - online: Miner is actively mining and connected - offline: Miner is not connected or powered off - stale: Miner data is stale (no recent updates) - archived: (Asset) Miner has been archived - off_rack: (Asset) Miner is removed from rack - transit: (Asset) Miner is in transit - maintenance: (Asset) Miner is under maintenance - retired: (Asset) Miner has been retired - error: Deprecated. Use anomaly_filters. - low_hashrate: Deprecated. Use hashrate_realization range. - overheated: Deprecated. Use anomaly_filters=temperature. - overpower: Deprecated. Use anomaly_filters=power. - underpower: Deprecated. Use anomaly_filters=power. - overclocking: Deprecated. Use mining_modes_in with overclocking presets. schema: example: online type: array items: type: string enum: - online - offline - stale - sleep - unknown - archived - off_rack - transit - maintenance - retired - error - low_hashrate - overheated - overpower - underpower - overclocking - name: tags required: false in: query description: >- Filter miners by tags (operator-managed labels). Overlap match — a miner matches if it carries any of the values. Preset values: `maintenance`, `retired`, `off_rack`, `transit`, `archived`, plus free-form custom tags. Supports multiple values separated by `,` or multiple query parameters. schema: example: archived type: array items: type: string minLength: 1 - name: unstable required: false in: query description: >- Unstable filter. `true` returns only miners with non-null `unstable_reason` (mac/sn unreliable). Omit, null, or false to include unstable miners. schema: example: false type: boolean - name: has_anomaly required: false in: query description: >- Abnormal axis (the whole `anomaly_flags` bitmask, not a specific type). `true` = any anomaly bit set (anomaly_flags <> 0) — the overview "abnormal" scope. `false` = no anomaly bits (anomaly_flags = 0) — the fault-free scope behind "healthy"/"sleep". Omit to include both. Prefer this over OR-ing all `anomaly_filters` for the abnormal aggregate. schema: example: false type: boolean - name: anomaly_filters required: false in: query description: >- Filter miners by anomaly type (OR semantics — returns miners matching ANY of the specified types). Available values: fan, power, temperature, hashboard, network, firmware, unknown, control_board, pool, low_hashrate. Corresponds to bits in the anomaly_flags bitmask field on each miner. Accepts repeated array (anomaly_filters[]=fan&anomaly_filters[]=power), comma-separated string (anomaly_filters=fan,power), or single value (anomaly_filters=fan). schema: type: array example: - fan items: type: string enum: - fan - power - temperature - hashboard - network - firmware - unknown - control_board - pool - low_hashrate - name: hashrate_realization_min required: false in: query description: >- Lower bound of hashrate realization rate (actual / expected). 1.0 = 100%. Miners with NULL or 0 expected_hashrate are excluded. schema: example: 0.8 type: number minimum: 0 - name: hashrate_realization_max required: false in: query description: >- Upper bound of hashrate realization rate. No hard cap (allows >1 for overclocked miners). schema: example: 1.2 type: number minimum: 0 - name: mining_modes_in required: false in: query description: >- Filter miners by mining_mode value (OR semantics — returns miners matching ANY of the specified modes). Accepts repeated array (mining_modes_in[]=high&mining_modes_in[]=power_tuning), comma-separated string (mining_modes_in=high,power_tuning), or single value (mining_modes_in=high). schema: type: array example: - high - power_tuning - hashrate_tuning items: type: string minLength: 1 - name: ip_ranges required: false in: query description: >- Filter miners by IPv4 ranges. A miner matches if its IP falls into any of the provided ranges. Each item accepts one of three forms: - single address (e.g. `192.168.1.5`) - CIDR (e.g. `192.168.1.0/24`) - hyphen range (e.g. `192.168.1.1-192.168.1.254`, inclusive) Supports multiple values separated by `,` or repeated query parameters. schema: example: 192.168.1.5,192.168.144.0/24,10.0.0.1-10.0.0.50 maxItems: 10 type: array items: type: string pattern: >- ^(?:(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)\/(?:3[0-2]|[12]?\d)|(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)-(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?))$ responses: '200': description: Successfully retrieved granted miner status 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: Miner Id example: 002b1a50fa281efe0f320ebc39f5047b 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 serial_number: description: Serial number example: HTM3FS28HD25011939878367054H36045 type: - string - 'null' model: description: Miner model example: Antminer S19 type: - string - 'null' ip: type: string description: IP address example: 192.168.1.100 mac: type: string description: MAC address example: 00:1B:44:11:3A:B7 network: default: null description: >- Network configuration read from the miner, null before the agent has reported it properties: mode: description: How the address is assigned enum: - dhcp - static type: - string - 'null' ip: description: Address currently in use type: - string - 'null' netmask: description: Subnet mask currently in use type: - string - 'null' gateway: description: >- Gateway in use. Null when the firmware does not report one, which is the case for Antminer derivatives on DHCP type: - string - 'null' dns: description: >- DNS servers in use, semicolon separated when there are several type: - string - 'null' required: - mode - ip - netmask - gateway - dns type: - object - 'null' firmware_version: description: Firmware version example: 20250304.15.REL type: - string - 'null' rack: description: >- Rack identifier where the miner is physically located. Null when the miner has not been assigned to a rack. example: A1 type: - string - 'null' position: description: >- Slot position within the rack (1-based). Null when the miner has not been assigned to a rack slot. example: 3 minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' is_mining: type: boolean description: Whether the miner is actively mining example: true last_check_succeed: type: boolean description: Whether the last health check succeeded example: true stale: type: boolean description: Whether the miner has stale data example: false overheat: type: boolean description: >- Deprecated. Check anomaly_flags with `temperature` bit. Always false. example: false deprecated: true low_hashrate: type: boolean description: >- Deprecated. Derive from hashrate / expected_hashrate. Always false. example: false deprecated: true overpower: type: boolean description: >- Deprecated. Check anomaly_flags with `power` bit. Always false. example: false deprecated: true underpower: type: boolean description: >- Deprecated. Check anomaly_flags with `power` bit. Always false. example: false deprecated: true status: type: string description: >- Run status. `online` = currently reporting; `stale` = no recent reports. example: online enum: - online - stale tags: default: [] description: >- Operator-managed labels (multi-value). Preset values: maintenance / retired / off_rack / transit / archived, plus free-form custom tags. Empty array when none set. example: [] type: array items: type: string ops_status: deprecated: true description: >- Deprecated; always null. Operator labels moved to `tags`. type: - string - 'null' lifecycle_status: deprecated: true description: >- Deprecated; always null. Derive from `status` and `tags`. type: - string - 'null' unstable_reason: description: >- Unstable reason. NULL when miner is stable (mac/sn valid + unique). Set when the raw could not be reliably matched to a stable identity (mac_invalid / mac_duplicate / sn_invalid / sn_duplicate / mac_empty / sn_empty / all_invalid / ip_only). example: null type: - string - 'null' health_status: description: >- Deprecated. Replaced by anomaly_flags (anomalies), derived hashrate/expected_hashrate (low hashrate), and mining_mode (overclocking). Always null. example: null deprecated: true type: - string - 'null' anomaly_flags: default: 0 description: >- Bitmask of active anomaly types. Each bit corresponds to a specific anomaly: bit 0=fan, 1=power, 2=temperature, 3=hashboard, 4=network, 5=firmware, 6=unknown, 8=control_board, 9=pool. Use bitwise AND to check for specific anomalies. example: 0 type: integer minimum: -9007199254740991 maximum: 9007199254740991 mining_mode: type: string description: >- Current mining mode of the miner. Possible values: sleep, low, normal, high AntMiner supports: sleep, low, normal WhatsMiner supports: sleep, low, normal, high Reference: https://github.com/UpstreamData/pyasic/blob/master/pyasic/config/mining/__init__.py example: normal mining_mode_preset: description: >- Processed preset name for preset-mode miners. Null for non-preset miners. type: - string - 'null' hashrate: description: Hashrate value in H/s example: 100120000000000 type: - number - 'null' expected_hashrate: description: Expected hashrate in H/s example: 125000000000000 type: - number - 'null' hashrate_24h: description: 24-hour average hashrate in H/s example: 100120000000000 type: - number - 'null' power: description: Power consumption in watts example: 9771 type: - number - 'null' temp: description: Temperature in Celsius example: 75.5 type: - number - 'null' temperature_inlet_avg: description: Average inlet temperature in Celsius example: 35.5 type: - number - 'null' temperature_outlet_avg: description: Average outlet temperature in Celsius example: 65.5 type: - number - 'null' efficiency: description: Power efficiency in J/TH example: 34 type: - number - 'null' uptime: type: number description: Uptime in seconds example: 86400 last_updated_at: description: Timestamp of last updated. ISO Format example: '2025-08-27T00:00:00Z' type: - string - 'null' created_at: description: >- Timestamp when the agent first discovered and registered this miner. ISO Format. Persistent — not reset by reboots or rescans. example: '2025-08-27T00:00:00Z' type: - string - 'null' errors: type: array items: type: object properties: code: type: string description: Error code example: E001 message: description: Error message example: Temperature too high type: - string - 'null' required: - code - message description: Array of error objects hashboards: type: array items: type: object properties: serial_number: description: Hashboard serial number example: HB123456 type: - string - 'null' hashrate: description: Hashboard hashrate in H/s example: 25120000000000 type: - number - 'null' chips: description: Number of chips on the hashboard example: 4 type: - number - 'null' chip_frequency: description: Chip frequency in MHz example: 650 type: - number - 'null' required: - serial_number - hashrate - chips - chip_frequency description: Array of hashboard objects total_chips: description: Total number of chips example: 5 type: - number - 'null' expected_chips: description: Expected number of chips example: 4 type: - number - 'null' pools: default: [] description: Array of pool objects type: array items: type: object properties: url: description: Mining pool URL example: stratum+tcp://pool.example.com:4444 type: string worker_id: description: Worker ID for the mining pool example: worker1.100x0x217 type: string difficulty_accepted: description: Accepted share difficulty example: 354515730432 type: - number - 'null' difficulty_rejected: description: Rejected share difficulty example: 53477376 type: - number - 'null' difficulty_stale: description: Stale share difficulty example: 0 type: - number - 'null' psus: default: [] description: Array of power supply unit objects type: array items: type: object properties: serial_number: description: Power supply unit serial number example: 1717A2446600193 type: - string - 'null' temperature: description: Power supply unit temperature in Celsius example: 56.7 type: - number - 'null' required: - serial_number - temperature reboot_count: description: >- Total reboots aggregated from daily miner_metrics over the default 7-day window. Null when no metrics have been computed yet. >= 10 in 7 days is considered high-frequency. minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' low_uptime_reboot_count: description: >- Reboots where pre-reboot uptime was < 10 min (boot cycling), aggregated over the default 7-day window. Null when no metrics have been computed yet. High ratio (> 50% of reboot_count) suggests hardware fault. minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' required: - id - farm_id - farm - workspace_id - serial_number - model - ip - mac - firmware_version - rack - position - is_mining - last_check_succeed - stale - overheat - low_hashrate - overpower - underpower - status - ops_status - lifecycle_status - unstable_reason - health_status - mining_mode - mining_mode_preset - hashrate - expected_hashrate - hashrate_24h - power - temp - temperature_inlet_avg - temperature_outlet_avg - efficiency - uptime - last_updated_at - created_at - errors - hashboards - total_chips - expected_chips - reboot_count - low_uptime_reboot_count title: Miner 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: securitySchemes: clerk-api-key: scheme: bearer bearerFormat: API Key type: http description: Clerk Machine API Key for authentication ````