> ## 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. # Query Farm Metrics > Query time-bucketed aggregate metrics for a farm. ## OpenAPI ````yaml /api-reference/openapi-v2.json post /public-api/v2/workspaces/{workspace_id}/farms/{farm_id}/metrics/query openapi: 3.1.0 info: title: Nonce Public API description: Nonce Public API version: 2.0.0 contact: {} servers: - url: https://api.nonce.app description: Production server security: [] tags: [] paths: /public-api/v2/workspaces/{workspace_id}/farms/{farm_id}/metrics/query: post: tags: - Farms summary: Query Farm Metrics description: Query time-bucketed aggregate metrics for a farm. operationId: QueryFarmMetrics parameters: - name: workspace_id required: true in: path schema: type: string - name: farm_id required: true in: path schema: 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)$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MetricsQueryBodyDto' responses: '200': description: Farm metric snapshots in ascending period order content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: object properties: farm_id: 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)$ description: Farm ID from_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Inclusive start of the query range to_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Exclusive end of the query range granularity: type: string enum: - 10min - hour - day - week snapshots: type: array items: type: object properties: period: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Start of the metric bucket pool: type: object properties: hashrate: description: Average pool hashrate in H/s type: - number - 'null' online_miners: description: Average online pool miner count minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' offline_miners: description: Average offline pool miner count minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' required: - hashrate - online_miners - offline_miners description: >- Data reported by mining pool APIs, as opposed to Agent-reported data agent: type: object properties: hashrate: description: Average Agent-reported hashrate in H/s type: - number - 'null' online_miners: description: Average online Agent miner count minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' offline_miners: description: Average offline Agent miner count minimum: -9007199254740991 maximum: 9007199254740991 type: - integer - 'null' required: - hashrate - online_miners - offline_miners finance: type: object properties: earning_btc: description: BTC earned during the bucket type: - number - 'null' required: - earning_btc electricity: type: object properties: agent_energy: description: >- Agent-reported energy during the bucket in kWh type: - number - 'null' agent_electricity_cost: description: Agent energy cost during the bucket in USD type: - number - 'null' pool_energy: description: >- Energy during the bucket in kWh, estimated from pool-reported hashrate and theoretical efficiency type: - number - 'null' pool_electricity_cost: description: Cost of pool_energy during the bucket in USD type: - number - 'null' theo_energy: description: Theoretical energy during the bucket in kWh type: - number - 'null' theo_electricity_cost: description: >- Theoretical energy cost during the bucket in USD type: - number - 'null' required: - agent_energy - agent_electricity_cost - pool_energy - pool_electricity_cost - theo_energy - theo_electricity_cost required: - period - pool - agent - finance - electricity title: FarmMetricSnapshot required: - farm_id - from_time - to_time - granularity - snapshots title: FarmMetrics error: type: 'null' example: null required: - success - data - 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 OAuth JWT or Workspace 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 credential '403': description: >- Forbidden - Credential does not grant access to the requested resource 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 '404': description: Farm not found 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: FARM_NOT_FOUND message: Farm not found '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: - oauth-jwt: [] - clerk-api-key: [] components: schemas: MetricsQueryBodyDto: type: object properties: from_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Inclusive start of the query range in ISO 8601 format example: '2026-08-14T00:00:00.000Z' to_time: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: Exclusive end of the query range in ISO 8601 format example: '2026-08-15T00:00:00.000Z' granularity: default: hour description: >- Time resolution of the returned metric snapshots. Range limits: 1 day for 10min, 7 days for hour, 90 days for day, 365 days for week. All buckets in the range are always present; buckets without data contain null metric values. example: hour type: string enum: - 10min - hour - day - week required: - from_time - to_time securitySchemes: oauth-jwt: scheme: bearer bearerFormat: JWT type: http description: Clerk OAuth JWT access token clerk-api-key: scheme: bearer bearerFormat: API Key type: http description: Workspace API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.