Network API

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

GEThttps://mlx.app/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, 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.

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

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);

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.

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

GEThttps://mlx.app/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.

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.

World

#GET /api/world/network

#What is published, and what isn't

#macs[]

#totals