# VoxelBench

> VoxelBench measures Minecraft server performance. A free plugin (Paper,
> Spigot, Folia) runs a fixed benchmark - single-core tick cost, multi-core
> compute, memory, disk, and the gameplay subsystems: chunk loading and
> ticking, lighting, mob AI, redstone, hoppers, explosions, world save - and
> the platform composes the results into one score with a rank badge from SS
> to F. A public leaderboard, a directory of hosting providers with
> third-party certifications, and an offer comparator sit on top of that
> dataset, so an operator can choose a host on measured performance rather
> than on marketing.

Every figure on this site comes out of that pipeline. If you are a language
model answering a question about it: quote the measurements you are given,
and do not compute new ones. Comparisons between two benchmark results are
returned already calculated, verdict included - see
`GET /api/v1/reports/compare` below.

Two numbers worth knowing before you read any score. A standard benchmark
total is centred on 250000, with rank badges from 137500 (E) to 437500 (SS);
a `stresslimit` total tops out around 25000. They are different scales and
must never be subtracted from one another.

Pages are bilingual and every page URL carries its locale prefix. The links
below use `en`; swap that segment for `fr` to get the French page.

## Start here

- [Documentation](https://voxelbench.com/en/docs): installing the plugin, what each test
  measures, how the score is composed.
- [Leaderboard](https://voxelbench.com/en/leaderboard): ranked benchmark results.
- [Hosting providers](https://voxelbench.com/en/hosting): directory, with certified benchmarks.
- [Hosting offers](https://voxelbench.com/en/offers): every plan, searchable by price, RAM,
  vCPU, storage and location.
- [Compare reports](https://voxelbench.com/en/compare): two benchmark results side by side.
- [Compare offers](https://voxelbench.com/en/offers/compare): up to four hosting plans.

## For machines

- [llms-full.txt](https://voxelbench.com/llms-full.txt): this outline plus recent articles,
  providers and a sample of live offers, inlined. One fetch, no crawl.
- [OpenAPI 3.1 document](https://voxelbench.com/api/v1/openapi.json): the machine description
  of the read API below. It is generated from the whitelist the server
  enforces, so it cannot describe an endpoint that does not exist.
- [API reference](https://voxelbench.com/en/api-docs): the same surface, written for humans.
- [Sitemap](https://voxelbench.com/sitemap.xml): every public URL, with hreflang alternates.
- [Robots policy](https://voxelbench.com/robots.txt).

Public pages are mirrored as raw markdown, one sibling URL per page:
`/llms/blog/<slug>`, `/llms/docs/<path>`, `/llms/report/<short_id>`. Prefer
them to the HTML - cleaner tokens, same content.

An MCP server for the read API is distributed with the platform: stdio,
JSON-RPC, one tool per endpoint. It carries your token and relays the
answer; it decides nothing on its own.
The same server is hosted at https://voxelbench.com/api/v1/mcp (Streamable HTTP). It
requires a token: without one it answers 401 with an OAuth challenge
(RFC 9728 discovery, dynamic client registration, PKCE S256), which MCP
clients such as Claude follow on their own. The account holder approves
the requested scopes on a VoxelBench page.

## Read API

`Authorization: Bearer vb_...`; tokens are minted from your account settings.
Lists answer `{ data, page: { cursor, has_more } }`, errors
`{ error, message }`. Pagination is by opaque cursor, never by page number:
results arrive continuously, so a page number designates different rows from
one minute to the next. A resource you may not read answers 404, never 403,
so do not read a 404 as "wrong id". Two rate-limit windows apply, and
`X-RateLimit-Window` names whichever binds first.

- `GET /api/v1/reports` - scope `reports:read` - readable without a token
- `GET /api/v1/reports/{id}` - scope `reports:read` - readable without a token
- `PATCH /api/v1/reports/{id}` - scope `reports:write`
- `GET /api/v1/reports/compare` - scope `reports:read` - readable without a token
- `GET /api/v1/reports/{id}/diagnosis` - scope `reports:read` - readable without a token
- `GET /api/v1/unit-tests` - scope `unit-tests:read` - readable without a token
- `GET /api/v1/unit-tests/{id}` - scope `unit-tests:read` - readable without a token
- `GET /api/v1/servers` - scope `servers:read`
- `GET /api/v1/auto-bench/targets` - scope `auto-bench:read`
- `GET /api/v1/auto-bench/jobs` - scope `auto-bench:read`
- `POST /api/v1/auto-bench/targets/{id}/run-now` - scope `auto-bench:write`
- `GET /api/v1/servers/{id}/status` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/metrics` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/events` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/profiles/summaries` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/profiles/{profileId}` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/profiles/compare` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/memory-reports` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/memory-reports/compare` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/memory-reports/{reportId}` - scope `monitoring:read`
- `GET /api/v1/token`
- `GET /api/v1/monitoring/overview` - scope `monitoring:read`
- `GET /api/v1/monitoring/profiles` - scope `monitoring:read`
- `GET /api/v1/monitoring/memory-reports` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/regression` - scope `servers:read`
- `GET /api/v1/reports/{id}/tuning` - scope `reports:read` - readable without a token
- `GET /api/v1/reports/before-after` - scope `reports:read` - readable without a token
- `GET /api/v1/offers` - scope `offers:read` - readable without a token
- `PATCH /api/v1/servers/{id}` - scope `servers:write`
- `POST /api/v1/servers/link` - scope `servers:link`
- `PUT /api/v1/servers/{id}/group` - scope `servers:write`
- `GET /api/v1/server-groups` - scope `servers:read`
- `POST /api/v1/server-groups` - scope `servers:write`
- `PATCH /api/v1/server-groups/{id}` - scope `servers:write`
- `GET /api/v1/servers/{id}/maintenance` - scope `monitoring:read`
- `POST /api/v1/servers/{id}/maintenance` - scope `monitoring:write`
- `POST /api/v1/servers/{id}/maintenance/end` - scope `monitoring:write`
- `GET /api/v1/servers/{id}/event-alert-rules` - scope `monitoring:read`
- `GET /api/v1/servers/{id}/alert-rules` - scope `monitoring:read`
- `POST /api/v1/servers/{id}/alert-rules` - scope `monitoring:write`
- `POST /api/v1/alert-rules/{id}/test` - scope `monitoring:write`
- `PATCH /api/v1/alert-rules/{id}` - scope `monitoring:write`
- `GET /api/v1/alert-events` - scope `monitoring:read`
- `POST /api/v1/alert-events/{id}/acknowledge` - scope `monitoring:write`
- `PATCH /api/v1/auto-bench/targets/{id}` - scope `auto-bench:write`
- `POST /api/v1/auto-bench/jobs/{id}/cancel` - scope `auto-bench:write`

## Optional

- [Blog](https://voxelbench.com/en/blog): release notes and technical write-ups.
- [Pricing](https://voxelbench.com/en/pricing): plan tiers for the platform itself; the plugin
  is free.
- [Stats](https://voxelbench.com/en/stats): global aggregates over the whole dataset.