> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Machine Credit Rating

> Fetch a machine's MCR from the peaqOS MCR API. Covers curl, JavaScript, and Python.

The MCR API returns a machine's credit rating along with event counts, revenue trend, and bond status. It's a public read API. No authentication required.

## Endpoint

```
GET {PEAQOS_MCR_API_URL}/mcr/{did}
```

`{did}` accepts either a full DID (`did:peaq:0xabc...`) or a raw EVM address (`0xabc...`). Set `PEAQOS_MCR_API_URL` to the root of the MCR API server. The public peaq-hosted MCR is at `https://mcr.peaq.xyz`. Self-hosted deployments default to `http://127.0.0.1:8000`.

## Fetch the MCR

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  curl -s "${PEAQOS_MCR_API_URL}/mcr/did:peaq:0xabc1230000000000000000000000000000000001"
  ```

  ```typescript JS/TS theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  const did = "did:peaq:0xabc1230000000000000000000000000000000001";
  const response = await fetch(
    `${PEAQOS_MCR_API_URL}/mcr/${encodeURIComponent(did)}`
  );

  if (!response.ok) {
    throw new Error(`MCR API returned ${response.status}`);
  }

  const mcr = await response.json();
  console.log("Rating:", mcr.mcr);
  console.log("Score:", mcr.mcr_score);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  import requests

  did = "did:peaq:0xabc1230000000000000000000000000000000001"
  response = requests.get(
      f"{os.environ['PEAQOS_MCR_API_URL']}/mcr/{did}"
  )
  response.raise_for_status()

  mcr = response.json()
  print("Rating:", mcr["mcr"])
  print("Score:", mcr["mcr_score"])
  ```
</CodeGroup>

## Response shape

```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
  "did": "did:peaq:0xabc1230000000000000000000000000000000001",
  "machine_id": 1,
  "mcr_score": 45,
  "mcr": "BB",
  "mcr_degraded": false,
  "bond_status": "bonded",
  "negative_flag": false,
  "event_count": 12,
  "revenue_event_count": 7,
  "activity_event_count": 5,
  "revenue_trend": "stable",
  "total_revenue": 35000,
  "average_revenue_per_event": 5000.0,
  "last_updated": 1711900000
}
```

`total_revenue` and `average_revenue_per_event` are USD cents. Divide by 100 for display ($350 and $50 in this example).

A newly registered machine that hasn't accumulated enough history returns `mcr: "Provisioned"` with `mcr_score: 0`. Unbonded machines return `mcr: "NR"` with `mcr_score: 0`. See [GET /mcr/\{did}](/peaqos/api-reference/get-mcr) for the full field reference.

## Query an operator's fleet

Use the operator endpoint to list all machines registered under a proxy operator, paginated with MCR scores per machine.

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  curl -s "${PEAQOS_MCR_API_URL}/operator/did:peaq:0xProxyAddress/machines?offset=0&limit=20"
  ```

  ```typescript JS/TS theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  const operatorDid = "did:peaq:0xProxyAddress";
  const response = await fetch(
    `${PEAQOS_MCR_API_URL}/operator/${encodeURIComponent(operatorDid)}/machines?offset=0&limit=20`
  );
  const { machines } = await response.json();

  for (const m of machines) {
    console.log(`Machine ${m.machine_id}: ${m.mcr}`);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  import os
  import requests

  operator_did = "did:peaq:0xProxyAddress"
  response = requests.get(
      f"{os.environ['PEAQOS_MCR_API_URL']}/operator/{operator_did}/machines",
      params={"offset": 0, "limit": 20},
  )
  response.raise_for_status()

  for m in response.json()["machines"]:
      print(f"Machine {m['machine_id']}: {m['mcr']}")
  ```
</CodeGroup>

See [GET /operator/\{did}/machines](/peaqos/api-reference/get-operator-machines) for the full response shape and pagination details.

## Caching

The server applies a 1-hour TTL on MCR responses by default, configurable via the `MCR_CACHE_TTL` env var (`0` to disable). Repeat requests within the window return cached values. The `last_updated` field tells you when the underlying events were most recently added.

## Error handling

The MCR API returns standard HTTP status codes: `404` when the DID is unregistered, `503` when the chain is unavailable, `400` for malformed inputs. Bodies are JSON with a `detail` field carrying the upstream message.

If you call through the SDK (`queryMcr(client, did)` in JS / `query_mcr(client, did)` in Python), HTTP failures surface as `RuntimeError` (JS) or `ApiError` (Python). The `code` attribute carries `NOT_FOUND`, `SERVICE_UNAVAILABLE`, `SERVER_ERROR`, `TIMEOUT`, etc. See [SDK errors reference](/peaqos/sdk-reference/errors) for the full code map.

## Next steps

* [GET /mcr/\{did}](/peaqos/api-reference/get-mcr): full API reference for this endpoint
* [GET /machine/\{did}](/peaqos/api-reference/get-machine): full machine profile
* [Machine Credit Rating concept](/peaqos/concepts/machine-credit-rating): rating scale and lifecycle