> ## 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.

# GET /metadata/{token_id}

> Return NFT metadata for a MachineNFT token, intended as an ERC-721 tokenURI target.

## Endpoint

```http theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
GET /metadata/{token_id}
```

Returns NFT metadata for a MachineNFT token. The server looks up the machine ID from the token ID via the MachineNFT contract, then resolves the machine owner address and builds the same response as [GET /machine/{did}](/peaqos/api-reference/get-machine). This endpoint is designed to serve as an ERC-721 `tokenURI` target.

## Path parameters

<ParamField path="token_id" type="integer" required default="1">
  NFT token ID (not the machine ID)
</ParamField>

## Response

**200 OK**

The response shape is identical to [GET /machine/{did}](/peaqos/api-reference/get-machine). All base fields and data visibility-dependent fields apply. See that page for the full field reference.

| Field                      | Type           | Description                                                                                                                                                                                                                       |
| :------------------------- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version`           | string         | Always `"1.0"`                                                                                                                                                                                                                    |
| `name`                     | string         | `"Machine #<token_id>"` when the token round-trips, or `"Machine (no NFT)"` if the on-chain NFT lookup returns 0                                                                                                                  |
| `peaqos.machine_id`        | integer        | On-chain machine ID resolved from the token                                                                                                                                                                                       |
| `peaqos.did`               | string         | Machine DID derived from the owner address (`did:peaq:<owner_address>`)                                                                                                                                                           |
| `peaqos.operator`          | string or null | Operator DID from the DID document                                                                                                                                                                                                |
| `peaqos.mcr`               | string         | Letter rating: `AAA`, `AA`, `A`, `BBB`, `BB`, `B`, `NR`, or `Provisioned`                                                                                                                                                         |
| `peaqos.mcr_score`         | integer        | MCR score 0-100                                                                                                                                                                                                                   |
| `peaqos.bond_status`       | string         | `"bonded"` or `"unbonded"`                                                                                                                                                                                                        |
| `peaqos.negative_flag`     | boolean        | `true` when the AdminFlags contract has a negative-flag timestamp set for this machine. Stays `true` for as long as the timestamp is recorded on-chain, regardless of whether the 180-day MCR scoring penalty is still in effect. |
| `peaqos.event_count`       | integer        | Total on-chain event count                                                                                                                                                                                                        |
| `peaqos.data_visibility`   | string         | `"private"`, `"onchain"`, or `"public"`                                                                                                                                                                                           |
| `peaqos.documentation_url` | string or null | Public documentation URL from the DID document                                                                                                                                                                                    |

Additional fields (`data_api`, `event_data`, `partner_data`, `partner_data_error`) depend on `data_visibility`. See [GET /machine/{did}](/peaqos/api-reference/get-machine) for details.

## Error responses

| Status | `detail`                    | Condition                                                              |
| :----- | :-------------------------- | :--------------------------------------------------------------------- |
| 404    | `"Token not found"`         | Token ID does not map to any machine in the MachineNFT contract        |
| 404    | `"Machine not registered"`  | The token's machine ID is not present in the IdentityRegistry contract |
| 422    | (FastAPI validation error)  | `token_id` is less than 1 or not an integer                            |
| 503    | `"Service not initialised"` | Server started without contract addresses                              |
| 503    | `"Chain unavailable"`       | Any chain or DID call failed                                           |

## Example

<CodeGroup>
  ```bash bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  curl "${PEAQOS_MCR_API_URL}/metadata/7"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
  const response = await fetch(`${PEAQOS_MCR_API_URL}/metadata/7`);
  const data = await response.json();
  console.log(data.name, data.peaqos.mcr);
  ```

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

  response = requests.get(f"{PEAQOS_MCR_API_URL}/metadata/7")
  data = response.json()
  print(data["name"], data["peaqos"]["mcr"])
  ```
</CodeGroup>

**Response**

```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
  "schema_version": "1.0",
  "name": "Machine #7",
  "peaqos": {
    "machine_id": 42,
    "did": "did:peaq:0xabc1230000000000000000000000000000000001",
    "operator": "did:peaq:0xoperator0000000000000000000000000000001",
    "mcr": "B",
    "mcr_score": 30,
    "bond_status": "bonded",
    "negative_flag": false,
    "event_count": 5,
    "data_visibility": "onchain",
    "documentation_url": null,
    "event_data": [
      {
        "event_type": 0,
        "origin_value": 1500,
        "timestamp": 1711900000,
        "trust_level": 1,
        "metadata": {},
        "origin_currency": "USD",
        "origin_subunit": 100,
        "usd_value": 1500,
        "usd_subunit": 100,
        "amount_status": "ok"
      }
    ]
  }
}
```

## Related endpoints

* [GET /machine/{did}](/peaqos/api-reference/get-machine) returns the same response shape, resolved by DID instead of token ID.
* [GET /mcr/{did}](/peaqos/api-reference/get-mcr) returns a focused MCR response with revenue trend and summary.
* [GET /machines/{machine_id}](/peaqos/api-reference/get-machine-card) returns the peaqOS Machine Card resolved by numeric machine ID.