# World

The Macs that make up the network as MLX World shows them (every linked Mac seen in the last week, with public fields only and its approximate city), plus the network's totals and its output over the last day.

## GET /api/world/network {#network}

```endpoint try
GET /api/world/network?totals=1
```

Every Mac linked to a wallet and seen in the last week, and the network's totals. This is the data behind [world.mlx.app](https://world.mlx.app), the homepage's live map and the explorer's World tab. The response is rebuilt at most every few seconds and cached briefly at the CDN.

```bash tab=curl
curl "https://mlx.app/api/world/network?totals=1"
```

```js tab=JavaScript
const { totals, macs } = await (await fetch("https://mlx.app/api/world/network")).json();
console.log(`${totals.working} of ${totals.macs} Macs working, ${totals.tps} tokens/s`);
const byChip = Object.groupBy(macs, (m) => m.chip);
```

```python tab=Python
import requests

d = requests.get("https://mlx.app/api/world/network").json()
t = d["totals"]
print(t["working"], "of", t["macs"], "Macs working,", t["tps"], "tokens/s")
```

| Parameter | Type | Notes |
| --- | --- | --- |
| `totals` | `1` | Only `chain`, `at` and `totals`, without the list of Macs. |

```json title="Response"
{
  "chain": "mlx-1",
  "at": 1793116791648,
  "macs": [
    {
      "id": "51f9a4661bf41155",
      "kind": "macbook-pro",
      "art": "macbook-pro",
      "model": "MacBook Pro 16-inch",
      "year": 2024,
      "chip": "M4 Pro",
      "cls": "M",
      "memoryGB": 48,
      "activity": "working",
      "seen": 1793116781269,
      "geo": { "city": "Singapore", "region": "", "country": "SG", "lat": 1.3, "lon": 103.9 },
      "seat": "dedicated"
    }
  ],
  "totals": {
    "macs": 53,
    "online": 15,
    "working": 14,
    "tps": 426,
    "tokensToday": 14805599,
    "countries": 25,
    "cities": 46,
    "placed": 53,
    "freeNodes": 40,
    "freeTflops": 170.5,
    "freeMemGB": 1554
  },
  "capped": false
}
```

`macs` is trimmed to one Mac here.

### What is published, and what isn't

Each Mac is published with an explicit list of fields. Never its wallet, its own name, its IP address, its key, its work counters or its speed: those stay with the owner. The totals are sums over all Macs, so no single Mac's numbers show.

### `macs[]`

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | An opaque id, stable on this chain, that can't be turned back into the Mac's key. |
| `kind` | string | `macbook-air`, `macbook-pro`, `mac-mini`, `mac-studio`, `imac`, `mac-pro`, `macbook` or `mac` when unknown. |
| `art` | string | The drawing for it: `https://mlx.app/macs/<art>.svg`. |
| `model` | string | The model, such as "MacBook Pro 16-inch", from Apple's model identifier when MLX Node reports one, otherwise inferred. |
| `year` | integer | The model's year, when known. |
| `chip` | string | Short chip name, such as `M4 Pro`. |
| `cls` | `S`, `M`, `L` or null | The seat class the chip can carry in full: `S` Core (base chips), `M` Pro (Pro and Max), `L` Ultra. |
| `memoryGB` | integer | Unified memory the Mac reports. |
| `activity` | string | `working` (running jobs, or waiting between jobs on its seat's rhythm), `ready`, `paused`, `stopped`, `busy` (calibrating or downloading a model) or `offline` (no heartbeat for a few minutes). |
| `seen` | integer | Its last heartbeat, ms. |
| `geo` | object or null | Approximate place from the network's edge, rounded (no IP is kept): `city`, `region`, `country`, `lat`, `lon`. `null` when unknown. |
| `seat` | `dedicated` or `free` | Whether its wallet holds a dedicated seat. |

### `totals`

| Field | Type | Notes |
| --- | --- | --- |
| `macs` | integer | Macs listed (linked and seen in the last week). |
| `online` | integer | Macs not `offline`. |
| `working` | integer | Macs whose `activity` is `working`. |
| `tps` | integer | Tokens a second the network produced over the last few minutes, counted from finished jobs. Before that counter has data it falls back to the working Macs' own meters. |
| `tokensToday` | integer | AI tokens the Macs report for the current UTC day. |
| `countries`, `cities` | integer | Distinct places among Macs with a `geo`. |
| `placed` | integer | Macs with a `geo`. |
| `freeNodes` | integer | Linked Macs without a dedicated seat to carry (a wallet's Macs beyond its number of seats, the smallest ones). Each mines on a free seat. |
| `freeTflops`, `freeMemGB` | number | Those Macs: estimated compute by class, and memory as reported. |

`capped` is `true` when there were more Macs than the list holds; the newest seen are kept.

## GET /api/world/series {#series}

```endpoint try
GET /api/world/series
```

The network's output, one sample a minute for the last day, oldest first. The sequencer's scheduled run takes each sample from the totals above, so this is real history, not something collected while a page is open.

No parameters.

```json title="Response"
{
  "samples": [
    { "t": 1793030700000, "tps": 271, "online": 13, "working": 12 },
    { "t": 1793030760000, "tps": 272, "online": 12, "working": 12 }
  ]
}
```

`samples` is trimmed to two here.

| Field | Type | Notes |
| --- | --- | --- |
| `t` | integer | Start of the minute, ms. |
| `tps` | integer | `totals.tps` at that minute. |
| `online`, `working` | integer | `totals.online` and `totals.working` at that minute. |

A minute the scheduled run missed has no sample, so don't assume the points are evenly spaced.

## Errors

| Status | When |
| --- | --- |
| 500 | The data couldn't be read. |

Both endpoints ignore parameters they don't know.