# Collections and entities > The nine collections, how paging works, and the fields of every entity summary and detail document, with provenance and frozen records. URL: https://gpuninja.com/docs/api/collections Last updated: 2026-10-11 ## The nine collections | Collection | What it holds | Has web pages | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------- | | `chips` | GPU processors as their designer specifies them: architecture, cores, memory bus, reference clocks and TDP, launch price | Yes, `/chips` | | `boards` | Graphics cards you can buy, built on a chip by a vendor: VRAM fitted, clocks, dimensions, power connectors, offers | Yes, `/boards` | | `chassis` | Cases, rack servers and eGPU enclosures, with GPU clearance and slot count | Yes, `/chassis` | | `models` | AI models: parameter count, quantisation, minimum VRAM, context length | Yes, `/models` | | `platforms` | The host and software a benchmark was run on: CPU, chipset, PCIe generation, OS, driver, framework | No | | `benchmarks` | Benchmark definitions: suite, metric, unit, direction, methodology, and every result | No | | `motherboards` | Motherboards: socket, form factor and PCIe slots, for the Solution Builder | No | | `risers` | PCIe riser cables and vertical-mount kits: cable length, PCIe generation, lanes | No | | `sockets` | CPU sockets, each with the motherboards built for it | No | Each collection is at `/api/v1/{collection}`, and each entity at `/api/v1/{collection}/{slug}`. Discontinued chips, boards, chassis, motherboards and risers stay in their collections. `motherboards`, `risers` and `sockets` are API only: JSON, with no site page and no `.txt` companion. ## Collection pages A collection page lists 50 summaries, ordered by slug. Page 1 is the collection URL, and later pages are at `/page/2`, `/page/3` and so on. ```bash curl -s https://gpuninja.com/api/v1/boards curl -s https://gpuninja.com/api/v1/boards/page/2 ``` ```json { "apiVersion": "v1", "kind": "collection", "collection": "boards", "asOf": "2026-10-04T06:12:00Z", "page": 1, "pageSize": 50, "pageCount": 3, "totalItems": 123, "scope": "active", "items": [ { "slug": "asus-rog-strix-4090", "name": "ASUS ROG Strix GeForce RTX 4090 OC", "chipSlug": "ad102", "vendor": "ASUS", "vramGb": 24, "tdpW": 450, "lengthMm": 357.6, "slotWidth": 3.5, "lowestPriceUsd": 1999.99, "inStock": true, "status": "active", "links": { "self": "https://gpuninja.com/api/v1/boards/asus-rog-strix-4090", "page": "https://gpuninja.com/boards/asus-rog-strix-4090", "text": "https://gpuninja.com/boards/asus-rog-strix-4090.txt" } } ], "links": { "self": "https://gpuninja.com/api/v1/boards", "first": "https://gpuninja.com/api/v1/boards", "last": "https://gpuninja.com/api/v1/boards/page/3", "prev": null, "next": "https://gpuninja.com/api/v1/boards/page/2", "page": "https://gpuninja.com/boards", "text": "https://gpuninja.com/boards.txt", "active": "https://gpuninja.com/api/v1/boards", "all": "https://gpuninja.com/api/v1/boards/all" } } ``` (Abridged: a real page has up to 50 items.) - `pageSize` is always 50. `pageCount` is at least 1, even for an empty collection. - To read a whole collection, start at the collection URL and follow `links.next` until it is `null`. - `links.page` and `links.text` point at the matching catalog page and its `.txt`, or are `null` for `platforms`, `benchmarks`, `motherboards`, `risers` and `sockets`. - `totalItems` counts the items of this list, and `pageCount` is `totalItems` divided by 50, rounded up (at least 1). - A page's `asOf` is the latest timestamp among the items on it, each counting only its own values and offers. Platform and benchmark pages usually have `"asOf": null`. ### Current and discontinued items Chips, boards, chassis, motherboards and risers can be discontinued. Their collection URL lists only the current items: discontinued ones are left out, so `/api/v1/boards` is what you can still buy. Every item, discontinued ones included, is in the complete list at `/all`: ```bash curl -s https://gpuninja.com/api/v1/boards/all curl -s https://gpuninja.com/api/v1/boards/all/page/2 ``` - `scope` says which list a page belongs to: `"active"` for a default list that leaves discontinued items out, `"all"` for a complete list. Models, platforms, benchmarks and sockets are never discontinued, so their lists are always `"all"`. - `links.active` and `links.all` point at page 1 of the two lists, and are `null` for collections that are never discontinued. Each list pages and counts on its own: `totalItems` of `/all` is larger whenever something has been discontinued. - Only the lists are filtered. A discontinued item keeps its detail document at `/api/v1//`, and the search index and the compatibility documents (`fits`, `can-run`, `runs-on`) still include it, with its `status`, so you can filter them yourself. A discontinued board is API only: it has no page, no `.txt` and no `fits` or `can-run` document of its own, so its `links.page`, `links.text` and `compatibility` (`fits`, `canRun`) are `null`. - `all` is reserved: no item has the slug `all`, as none has `page`. ## Summary fields Summaries appear in collection pages and nested inside other documents. Every summary has `slug`, `name` and `links`. | Summary | Other fields | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chip | `vendor`, `architecture`, `maxVramGb`, `referenceTdpW`, `memoryBandwidthGbps`, `fp32Tflops`, `fp16Tflops`, `bf16Tflops`, `fp8Tflops`, `fp4Tflops`, `int8Tops`, `unknownFields`, `pcieGen`, `pcieLanes`, `launchDate`, `segment`, `status`, `boardCount` | | Board | `chipSlug`, `vendor`, `vramGb`, `tdpW`, `lengthMm`, `slotWidth`, `unknownFields`, `lowestPriceUsd`, `inStock`, `status` | | Chassis | `vendor`, `formFactor`, `maxGpuLengthMm`, `maxGpuSlots`, `psuIncludedW`, `expansionSlots`, `verticalMountSlots`, `lowestPriceUsd`, `inStock`, `status` | | Model | `publisher`, `parametersB`, `activeParametersB`, `quantization`, `minVramGb`, `contextLength`, `layers`, `hiddenSize`, `kvHeads`, `headDim`, `modality` | | Platform | `cpu`, `pcieGen`, `os`, `framework`, `frameworkVersion` | | Benchmark | `suite`, `workloadType`, `metric`, `unit`, `higherIsBetter`, `resultCount` | | Motherboard | `vendor`, `socketSlug`, `formFactor`, `pcieSlotCount`, `status` | | Riser | `vendor`, `lengthMm`, `pcieGen`, `lanes`, `status` | | Socket | `vendor`, `segment`, `motherboardCount` | A board summary carries its chip's slug, not its name. The chip's name is in the chip's own summary, in the board's detail document (`data.chip.name`), and in the search index. ## Entity detail documents A detail document wraps the entity in the envelope, with the entity itself under `data`: ```bash curl -s https://gpuninja.com/api/v1/boards/asus-rog-strix-4090 ``` ```json { "apiVersion": "v1", "kind": "board", "asOf": "2026-10-04T06:12:00Z", "data": { "slug": "asus-rog-strix-4090", "name": "ASUS ROG Strix GeForce RTX 4090 OC", "chip": { "slug": "ad102", "name": "NVIDIA GeForce RTX 4090", "links": { "self": "https://gpuninja.com/api/v1/chips/ad102", "page": "https://gpuninja.com/chips/ad102", "text": "https://gpuninja.com/chips/ad102.txt" } }, "vendor": "ASUS", "vramGb": 24, "vramType": "GDDR6X", "factoryBoostClockMhz": 2640, "tdpW": 450, "lengthMm": 357.6, "widthMm": 149.3, "slotWidth": 3.5, "powerConnectors": "1× 16-pin 12V-2x6", "recommendedPsuW": 1000, "coolingType": "air, triple fan", "status": "active", "discontinuedAt": null, "lowestPriceUsd": 1999.99, "inStock": true, "offers": [ { "merchant": "Newegg", "price": 1999.99, "currency": "USD", "inStock": true, "retrievedAt": "2026-10-04T06:12:00Z", "sourceUrl": "https://www.newegg.com/p/N82E16814126593" } ], "benchmarkResults": [], "compatibility": { "fits": "https://gpuninja.com/api/v1/boards/asus-rog-strix-4090/fits", "canRun": "https://gpuninja.com/api/v1/boards/asus-rog-strix-4090/can-run" }, "provenance": { "lengthMm": { "sourceUrl": "https://rog.asus.com/graphics-cards/", "retrievedAt": "2026-02-01T09:00:00Z", "lastVerifiedAt": "2026-09-30T00:00:00Z", "runId": "2026-09-30-research", "verificationStatus": "verified" } } }, "links": { "self": "https://gpuninja.com/api/v1/boards/asus-rog-strix-4090", "page": "https://gpuninja.com/boards/asus-rog-strix-4090", "text": "https://gpuninja.com/boards/asus-rog-strix-4090.txt" } } ``` (Abridged: `benchmarkResults` is emptied here.) The `data` fields per kind: | Kind | Fields in `data` | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chip` | `slug`, `name`, `vendor`, `architecture`, `dieName`, `processNode`, `shaderCores`, `tensorCores`, `rtCores`, `memoryBusWidthBits`, `maxVramGb`, `referenceBoostClockMhz`, `referenceTdpW`, `memoryBandwidthGbps`, `fp32Tflops`, `fp16Tflops`, `bf16Tflops`, `fp8Tflops`, `fp4Tflops`, `int8Tops`, `unknownFields`, `pcieGen`, `pcieLanes`, `launchMsrpUsd`, `launchDate`, `segment`, `pci` (`vendorId`, `deviceIds`), `status`, `discontinuedAt`, `boards` (board summaries), `benchmarkResults` (reference-design results only), `provenance` | | `board` | `slug`, `name`, `chip` (slug, name, links), `vendor`, `vramGb`, `vramType`, `factoryBoostClockMhz`, `tdpW`, `lengthMm`, `widthMm`, `slotWidth`, `powerConnectors`, `recommendedPsuW`, `coolingType`, `unknownFields`, `status`, `discontinuedAt`, `lowestPriceUsd`, `inStock`, `offers`, `benchmarkResults`, `compatibility` (`fits`, `canRun`), `provenance` | | `chassis` | `slug`, `name`, `vendor`, `formFactor`, `maxGpuLengthMm`, `maxGpuSlots`, `psuIncludedW`, `expansionSlots`, `verticalMountSlots`, `bundledRiser` (a riser summary, or `null`), `status`, `discontinuedAt`, `lowestPriceUsd`, `inStock`, `offers`, `compatibility` (`fits`), `provenance` | | `model` | `slug`, `name`, `publisher`, `parametersB`, `activeParametersB`, `quantization`, `minVramGb`, `contextLength`, `layers`, `hiddenSize`, `kvHeads`, `headDim`, `modality`, `license`, `benchmarkResults`, `compatibility` (`runsOn`), `provenance` | | `platform` | `slug`, `name`, `cpu`, `chipset`, `pcieGen`, `ramGb`, `os`, `driverVersion`, `framework`, `frameworkVersion`, `offers`, `benchmarkResults`, `provenance` | | `benchmark` | `slug`, `name`, `suite`, `workloadType`, `metric`, `unit`, `higherIsBetter`, `methodologyUrl`, `results` (every result for this benchmark), `provenance` | | `motherboard` | `slug`, `name`, `vendor`, `socket` (a socket summary), `formFactor`, `pcieSlots`, `status`, `discontinuedAt`, `offers`, `provenance` | | `riser` | `slug`, `name`, `vendor`, `lengthMm`, `pcieGen`, `lanes`, `status`, `discontinuedAt`, `offers`, `provenance` | | `socket` | `slug`, `name`, `vendor`, `segment`, `motherboards` (summaries of every motherboard for this socket, discontinued ones included) | Notes on particular fields: - `pci.vendorId` and `pci.deviceIds` are four lowercase hex digits with no `0x`, such as `10de` and `2684`. Device IDs are sorted and unique. - `powerConnectors` is one string listing each connector as `count× type`, separated by `, `. A card with no power connectors says `slot-powered`. - `discontinuedAt` is a date, set only when `status` is `discontinued`. - `chassis.maxGpuLengthMm` and `maxGpuSlots` are clearances, not the case's own dimensions. `expansionSlots` counts the case's expansion-slot positions, `verticalMountSlots` is the width in slots of its vertical GPU mount (`null` when it has none), and `bundledRiser` is the riser that ships with the case. - A chip's `memoryBandwidthGbps` (decimal GB/s) and `fp32Tflops` are dense peaks at the reference boost clock, as are `fp16Tflops`, `bf16Tflops`, `fp8Tflops`, `fp4Tflops` and `int8Tops`; a precision is `null` when the chip has no hardware support for it. - Unknown values. GPU Ninja lists well-known chips even when their designer hasn't published every figure. A field whose value is unknown is `null` (`pci.deviceIds` is `[]`), and the chip's `unknownFields` names it, for example `["shaderCores","int8Tops"]`. A `null` that isn't listed has its own meaning: no hardware support for a precision, no tensor or RT cores, no announced MSRP, no PCIe card interface, or not discontinued. - Boards carry `unknownFields` too (`["widthMm"]` when the vendor doesn't publish the card's height). Every board measurement is `null` when unknown; an unlisted `null` `recommendedPsuW` means the vendor publishes none. `pcieGen` and `pcieLanes` describe the chip's host interface, and are `null` when not recorded. - A model's `activeParametersB` is `null` for a dense model. `layers`, `hiddenSize`, `kvHeads` and `headDim` are its architecture, `null` when the publisher doesn't state them. - A motherboard's `pcieSlots` lists each PCIe slot by `position`, counted in expansion-slot positions from the top and starting at 1; positions need not be consecutive. `physicalLanes` is the connector's width and `electricalLanes` the lanes wired to it (1, 4, 8 or 16, never more than `physicalLanes`), and `pcieGen` the slot's generation. The slot list's provenance is keyed `pcieSlots`. - A riser's `lengthMm` is its cable length, not a card length; `pcieGen` and `lanes` are what it is rated for. - `compatibility` holds the absolute URLs of the entity's fit and can-run documents (see Compatibility (https://gpuninja.com/docs/api/compatibility)). ### Offers, price and stock An offer is one merchant listing: `merchant`, `price`, `currency`, `inStock`, `retrievedAt` and `sourceUrl` (the listing page, or `null`). `price` is a decimal amount in the offer's own currency. `retrievedAt` is when the current price and stock were observed; it changes only when one of them changes. Boards and chassis derive two summary fields from their offers: - `inStock` is `true` when any current offer, in any currency, is in stock. - `lowestPriceUsd` is the lowest price among in-stock US dollar offers. If no USD offer is in stock, it is the lowest USD price overall. With no USD offers at all, it is `null`. Offers in other currencies appear in `offers` but never in `lowestPriceUsd`. Offers are ordered by merchant, currency, price, then `sourceUrl`. A merchant has at most one offer per currency for each entity. Platforms, motherboards and risers also carry `offers`, but no derived `inStock` or `lowestPriceUsd`. Chips, models, benchmarks and sockets have no offers. ### Benchmark results Each result names its `benchmark` (with `metric`, `unit` and `higherIsBetter`), its `subject` (a board or a chip, with `kind`), the `model` it ran (or `null`), the `platform` it ran on, the measured `value` in the benchmark's unit, its `runDate`, and its `sourceUrl`. A chip's results are reference-design figures; a board's are for that card. `benchmark`, `subject`, `model` and `platform` carry a slug, a name and links, not the full entity. Results are ordered by benchmark slug, subject kind (`board` before `chip`), subject slug, model slug (results with no model first), platform slug, newest `runDate` first, then `sourceUrl` and `value`. ## asOf `asOf` on a detail document is the latest timestamp among the entity itself and every other entity that appears in the document (its chip, a chip's boards, the benchmark, subject, model and platform of each result, a motherboard's socket, a socket's motherboards and a case's bundled riser). Each of them contributes only its own timestamps: the `retrievedAt` and `lastVerifiedAt` of its provenance, and the `retrievedAt` of its offers and of their checks. A nested entity contributes its own values, not the `asOf` of its own detail document, so the rule never reaches further. `asOf` is `null` when there are none. Models, platforms and benchmarks without provenance therefore often have `"asOf": null`. The value comes from the data, never from the build, so it tells you how old the data is even when you're reading a cached copy. ## Provenance `data.provenance` maps a field name to where its value came from. Nested fields use a dotted name, such as `pci.vendorId`. A field with no entry has no recorded source. | Property | Meaning | | -------------------- | --------------------------------------------------------------------------------------------------------- | | `sourceUrl` | The page the value was taken from | | `retrievedAt` | When the current value was obtained | | `lastVerifiedAt` | When a source last confirmed it, or `null` | | `runId` | The daily research run that produced it, such as `2026-09-30-research`, or `null` for a maintainer's edit | | `verificationStatus` | How it was checked; see below | `verificationStatus` is an open vocabulary: accept values you don't recognise. Today's values are: - `verified`: the value was found on its source page. - `unverified`: the value is cited, but its source couldn't be fetched or didn't show it. It was kept and flagged for review. - `conflicting`: sources disagreed, and this value was chosen by the conflict rule. - `maintainer`: entered or confirmed by a maintainer. Offers and benchmark results carry their own `sourceUrl` rather than provenance entries. For how the data is researched and checked, see Data provenance (https://gpuninja.com/docs/data-provenance). ## Discontinued and frozen records When a chip, board, chassis, motherboard or riser is discontinued, its record becomes a frozen snapshot; a motherboard is frozen with its PCIe slots. Models, platforms, benchmarks and sockets never freeze. In the API: - `status` is `"discontinued"` and `discontinuedAt` is the date. - Its own fields, offers, benchmark results and provenance are published exactly as stored and are never refreshed. They change only through an explicit, reviewed correction. - For a board or case, `inStock` is `false` and `lowestPriceUsd` is `null` in its summaries, in the search index and in its detail document. The `offers` array still shows the last recorded offers, as history. - It keeps every URL and stays in its collection. - Derived answers keep updating: fit against newly added cases, can-run against newly added models, and its chip's list of boards. Summaries of other entities nested in its document, and so its envelope `asOf`, can change too. This is the frozen chassis example, abridged: ```json { "apiVersion": "v1", "kind": "chassis", "asOf": "2023-03-02T10:00:00Z", "data": { "slug": "nzxt-h510", "name": "NZXT H510", "status": "discontinued", "discontinuedAt": "2023-03-31", "lowestPriceUsd": null, "inStock": false, "offers": [ { "merchant": "Newegg", "price": 69.99, "currency": "USD", "inStock": false, "retrievedAt": "2023-03-02T10:00:00Z", "sourceUrl": null } ] } } ``` ## Ordering Every array has a fixed order, and string comparisons are by code unit, not locale. Collection items, a chip's `boards` and a socket's `motherboards` are ordered by slug; a motherboard's `pcieSlots` by `position`; offers by merchant, currency, price and `sourceUrl`; benchmark results as described above; device IDs in ascending hex. Fit, can-run and runs-on items have their own orders, given on Compatibility (https://gpuninja.com/docs/api/compatibility).