GET /operator/{did}/machines

GET

operator

{did}

machines

curl --request GET \
  --url https://mcr.peaq.xyz/operator/{did}/machines

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/operator/{did}/machines",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/operator/{did}/machines"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/operator/{did}/machines")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Endpoint

GET /operator/{did}/machines

Returns a paginated list of the machines an address owns or controls, with an for each machine. For a peaq-homed machine the score is computed from the machine’s full history (not bond-only). A Solana-homed machine is listed with mcr: "Provisioned" and mcr_score: 0: the listing does not read its indexed events, so use GET /mcr/{did} for its rating. A Solana-homed machine is listed under the peaq operator address recorded on its machine account, the operator that GET /machine/{did} returns; a machine with no operator set is not listed. The server reads which machines an address owns from an ownership index, then reads each listed machine’s data and score from the chain. A background worker builds the peaq half from MachineRegistry events up to the finalized block and polls about once a minute; the Solana half is a periodic snapshot of Solana-homed machines. On a 200 the index is at most 100 blocks behind the chain head as the worker last read it, and index in the body says how far; the gap to the current chain grows with index.head_observed_age_seconds. The route answers 503 instead of a list when the peaq half is more than 100 blocks behind, when its worker has not read the chain head for more than ten poll intervals (about ten minutes), or when the Solana snapshot is out of date. Large fleets iterate offset instead of asking for the whole list in one response.

Path parameters

string

required

Operator DID (did:peaq:0x...) or raw EVM address (0x...)

Query parameters

integer

default:"0"

Number of machines to skip before the returned page. Must be >= 0.

integer

default:"20"

Maximum number of machines to return per page. Range 1-20.

Response

200 OK

Field	Type	Description
`operator_did`	string	The operator DID as supplied in the request path
`machines`	array	Machines this address owns or controls (for the current page)
`machines[].did`	string	Machine DID: `did:peaq:<machine_id>`
`machines[].machine_id`	string	Machine ID as a decimal string
`machines[].mcr_score`	integer	MCR score 0-100. `0` for a Solana-homed machine.
`machines[].mcr`	string	Letter rating: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `NR`, or `Provisioned`. Always `"Provisioned"` for a Solana-homed machine; a bonded peaq-homed machine without enough history to score also reads `"Provisioned"`.
`machines[].negative_flag`	boolean	`true` when the AdminFlags contract has a negative-flag timestamp set for this machine. Stays `true` regardless of whether the 180-day MCR scoring penalty is still active.
`pagination`	object	Pagination metadata
`pagination.offset`	integer	The offset used for this page
`pagination.limit`	integer	The limit used for this page
`pagination.total`	integer	Number of machines the ownership index holds for this address, peaq-homed and Solana-homed together
`unreadable`	integer	Number of machines on this page the server could not read. `0` on a healthy read.
`index`	object	Where the peaq ownership index stood for this answer
`index.synced_to_block`	integer	Last peaq block the index had applied
`index.head_block`	integer	Finalized block as the index worker last read it
`index.blocks_behind`	integer	`head_block - synced_to_block`, never below `0`. At most `100` on a `200`
`index.head_observed_age_seconds`	integer	Seconds since the worker read `head_block`. The chain moves on by roughly one block every 7 seconds of this

A page can hold fewer entries than limit. A peaq-homed machine that no longer exists is skipped, and a machine the server could not read (including a Solana-homed machine that is relocating) is left out and counted in unreadable, so a non-zero unreadable means the page is incomplete for a reason other than ownership. An operator with no machines returns 200 with an empty machines array and pagination.total of 0.

Error responses

Status	`detail`	Condition
400	`"Empty DID"`	Path parameter is empty
400	`"Invalid Ethereum address format"`	DID or address does not match the expected hex format, including a machine DID such as `did:peaq:<decimal id>`
422	(FastAPI validation error)	`offset` or `limit` fails validation constraints
503	`"operator index syncing: block N of M"`	The peaq ownership index is more than 100 blocks behind, or its worker has not read the chain head for more than ten poll intervals. Before the worker’s first round the detail ends `of an unknown head`. A misconfigured start block past the chain head gives the same answer. Retry after the `Retry-After` header. The rate limiter sets that header on every response, including `200`, so key on the status and `detail`, not on the header
503	`"machines registered on another chain are not indexed yet; retry later"`	The Solana snapshot has not been taken or is out of date; retry after the `Retry-After` header
503	`"Service not initialised"`	Server started without contract addresses
503	`"Chain unavailable"`	Reading the ownership index failed. A failed read for a single machine is counted in `unreadable` instead of returning 503

Example

curl "${PEAQOS_MCR_API_URL:-https://mcr.peaq.xyz}/operator/did:peaq:0x47d0d49382bdbe6f969056aab22edc56cc59fe4f/machines?offset=0&limit=10"

const PEAQOS_MCR_API_URL = process.env.PEAQOS_MCR_API_URL ?? "https://mcr.peaq.xyz";
const response = await fetch(
  `${PEAQOS_MCR_API_URL}/operator/did:peaq:0x47d0d49382bdbe6f969056aab22edc56cc59fe4f/machines?offset=0&limit=10`
);
const data = await response.json();
console.log(data.machines.length, data.pagination.total, data.unreadable);

import os

import requests

PEAQOS_MCR_API_URL = os.environ.get("PEAQOS_MCR_API_URL", "https://mcr.peaq.xyz")

response = requests.get(
    f"{PEAQOS_MCR_API_URL}/operator/did:peaq:0x47d0d49382bdbe6f969056aab22edc56cc59fe4f/machines",
    params={"offset": 0, "limit": 10},
)
data = response.json()
print(len(data["machines"]), data["pagination"]["total"], data["unreadable"])

Response

{
  "operator_did": "did:peaq:0x47d0d49382bdbe6f969056aab22edc56cc59fe4f",
  "machines": [
    {
      "did": "did:peaq:<decimal machine id>",
      "machine_id": "<decimal machine id>",
      "mcr_score": 45,
      "mcr": "BB",
      "negative_flag": false
    },
    {
      "did": "did:peaq:<decimal machine id>",
      "machine_id": "<decimal machine id>",
      "mcr_score": 0,
      "mcr": "Provisioned",
      "negative_flag": false
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 2
  },
  "unreadable": 0,
  "index": {
    "synced_to_block": 11880328,
    "head_block": 11880328,
    "blocks_behind": 0,
    "head_observed_age_seconds": 58
  }
}

Response (index still syncing, 503)

{
  "detail": "operator index syncing: block 11,625,833 of 11,758,594"
}

GET /mcr/{did} returns detailed MCR data for a single machine, including revenue trend and summary.
GET /machine/{did} returns the full machine profile.

⌘I

GET /operator/{did}/machines

curl --request GET \
  --url https://mcr.peaq.xyz/operator/{did}/machines

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://mcr.peaq.xyz/operator/{did}/machines",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://mcr.peaq.xyz/operator/{did}/machines"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://mcr.peaq.xyz/operator/{did}/machines")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

​Endpoint

​Path parameters

​Query parameters

​Response

​Error responses

​Example

​Related endpoints

Endpoint

Path parameters

Query parameters

Response

Error responses

Example

Related endpoints