> ## 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 machine 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 (A unique, one-of-a-kind ownership token recorded on the chain. Unlike a coin, no two are interchangeable.) metadata for a machine token. A machine's token ID (The unique number identifying one specific token within a collection, like a serial number.) and its machine ID (Your machine's handle in every later call. It is derived from the machine type and credential subject (a large uint256, written as a decimal string).) are the same value, so the server checks that the token exists in MachineRegistry (or, for a Solana-homed machine, on its home chain) and builds the same response as [`GET /machine/{did}`](https://docs.peaq.xyz/peaqos/api-reference/get-machine) for `did:peaq:<token_id>`. This endpoint is designed to serve as an ERC-721 `tokenURI` target.

## Path parameters

**token\_id** `integer` *required* (default: 108934426058480933785963234320575706003575332367737915173645220784539698794848)

NFT token ID, which equals the decimal machine ID. Range `1` to `2^256-1`.

## Response

**200 OK**

The response shape is identical to [`GET /machine/{did}`](https://docs.peaq.xyz/peaqos/api-reference/get-machine): the same base fields, the optional `data_api`, and the extra fields a Solana-homed machine carries. See that page for the full field reference.

`peaqos.machine_id` is the token ID as a decimal string, `peaqos.did` is `did:peaq:<token_id>`, and `name` is `"Machine #<token_id>"`.

## Error responses

| Status | `detail` | Condition |
| :- | :- | :- |
| 404 | `"Token not found"` | No chain records a machine with this token ID |
| 409 | `{"code": "MACHINE_HOMED_ELSEWHERE", "home_protocol_chain_id", "message"}` | The machine is homed on a chain this server cannot read |
| 422 | (FastAPI validation error) | `token_id` is less than 1, above `2^256-1`, or not an integer |
| 429 | `"rate_limited"` | The server's budget for home-chain lookups is spent; slow down and retry |
| 503 | `"Machine is relocating to another chain; retry later"` | The machine is moving between chains |
| 503 | `"machine home chain is unreachable; retry later"` | Reading a Solana-homed machine's record failed |
| 503 | `"Service not initialised"` | Server started without contract addresses |
| 503 | `"Chain unavailable"` | Any chain call failed |

## Example

```bash bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
curl "${PEAQOS_MCR_API_URL:-https://mcr.peaq.xyz}/metadata/108934426058480933785963234320575706003575332367737915173645220784539698794848"
```

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

```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
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}/metadata/108934426058480933785963234320575706003575332367737915173645220784539698794848"
)
data = response.json()
print(data["name"], data["peaqos"]["mcr"])
```

**Response**

```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
{
  "schema_version": "1.0",
  "name": "Machine #108934426058480933785963234320575706003575332367737915173645220784539698794848",
  "peaqos": {
    "machine_id": "108934426058480933785963234320575706003575332367737915173645220784539698794848",
    "did": "did:peaq:108934426058480933785963234320575706003575332367737915173645220784539698794848",
    "operator": "did:peaq:0x47d0d49382bdbe6f969056aab22edc56cc59fe4f",
    "mcr": "Provisioned",
    "mcr_score": 0,
    "bond_status": "bonded",
    "negative_flag": false,
    "event_count": 0,
    "data_visibility": "private",
    "documentation_url": null
  }
}
```

## Related endpoints

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.