# /threedmark/results/search

`POST /api/threedmark/results/search`

Price: 20 credits

Search submitted 3DMark, PCMark and VRMark runs, ranked from the highest score down. Narrows by benchmark and preset, graphics card, processor, Apple system model, graphics vendor and card count, desktop or laptop, memory channel count, country, drive model, submission date range, a score ceiling, and graphics core, graphics memory and processor clock ranges. Each row carries the run id and URL, the submitting user and country, the processor and graphics card, the measured clocks, and every score the benchmark reports — the headline score plus graphics, CPU and combined components, thread-count scores for CPU Profile, bandwidth and access time for Storage, and the PCMark sub-scores.

## How to use it

`test` is the axis everything else hangs off: it selects a separate corpus, it decides which `score_type` values rank, and it decides which score fields a row carries — so read `scores` rather than assuming `graphics_score` exists. The hardware names match a leading fragment of the source's own catalogue and take the first entry, so pass a model as the driver reports it ('GeForce RTX 5090') and a Mac as a short fragment rather than its full parenthesised name. `country` is where the submitter was, not where the hardware was sold. Ranking is by score, so a run's position in one call is its rank under that `score_type`.

## Parameters

- `access-token` (string, required)

## Request body

- `timeout` (integer) — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
- `test` (string) — Which benchmark and preset to search. Every value is a separate corpus of runs, and the _mac values are the Apple-silicon editions (default: "time_spy"; one of: "time_spy", "time_spy_extreme", "speed_way", "steel_nomad_dx12", "steel_nomad_vulkan", "steel_nomad_light_dx12", "steel_nomad_light_vulkan", "port_royal", "solar_bay", "solar_bay_extreme_dx12", "solar_bay_extreme_vulkan", "fire_strike", "fire_strike_extreme", "fire_strike_ultra", "wild_life", "wild_life_extreme", "night_raid", "cpu_profile", "storage", "pcmark_10", "pcmark_10_v2_0", "pcmark_10_express", "pcmark_10_express_v2_0", "pcmark_10_extended", "pcmark_10_extended_v2_0", "vrmark_orange_room", "vrmark_cyan_room", "vrmark_blue_room", "steel_nomad_mac", "steel_nomad_light_mac", "solar_bay_mac", "solar_bay_extreme_mac", "wild_life_extreme_mac")
- `score_type` (string, nullable) — Which score the ranking is built on. Allowed values differ per test — Time Spy ranks by overall, graphics or physics, CPU Profile by a thread-count score, Storage by overall or bandwidth (one of: "all_cores_score", "bandwidth", "combined_score", "eight_cores_score", "four_cores_score", "graphics_score", "overall_score", "physics_score", "single_core_score", "sixteen_cores_score", "two_cores_score")
- `gpu` (string, nullable) — Graphics card name to restrict to; resolved to the closest catalogue entry upstream (examples: "GeForce RTX 5090", "Radeon RX 7900 XTX"; minLength: 1)
- `cpu` (string, nullable) — Processor name to restrict to; resolved to the closest catalogue entry upstream (examples: "Ryzen 9 9950X", "Core i9-14900K"; minLength: 1)
- `mac_model` (string, nullable) — Apple system model to restrict to, for the _mac tests only. The source matches it as a leading fragment of the catalogue name, so 'Mac mini' resolves and the full parenthesised name does not (examples: "Mac mini", "MacBook Pro", "Mac Studio"; minLength: 1)
- `gpu_vendor` (string, nullable) — Graphics vendor to restrict to (examples: "NVIDIA", "AMD", "INTEL"; minLength: 1)
- `gpu_count` (integer, nullable) — Number of graphics cards in the system (min: 1; max: 4)
- `device_type` (string, nullable) — Restrict to desktops or to laptops (examples: "DESKTOP", "LAPTOP"; minLength: 1)
- `memory_channel_count` (integer, nullable) — Number of populated memory channels (examples: 1, 2, 4)
- `country` (string, nullable) — ISO 3166-1 alpha-2 country the run was submitted from (examples: "DE", "JP"; minLength: 2)
- `storage_model` (string, nullable) — Exact drive model string, for the storage test only. It must match the string the drive reports; anything else returns no rows (examples: "Samsung SSD 990 PRO 2TB"; minLength: 1)
- `include_ram_disks` (boolean) — Include RAM-disk submissions, which the storage test excludes by default (default: false)
- `include_invalid_results` (boolean) — Include runs 3DMark marked invalid, which are excluded by default (default: false)
- `leaderboard_mode` (boolean) — Rank as the site's Leaderboard view rather than its Score Explorer view (default: false)
- `uploaded_after` (string, nullable) — Only runs submitted on or after this date (format: date)
- `uploaded_before` (string, nullable) — Only runs submitted on or before this date (format: date)
- `max_score` (integer, nullable) — Only runs whose ranking score is at or below this value (min: 0)
- `min_gpu_core_clock_mhz` (integer, nullable) — Minimum graphics core clock in MHz (min: 0)
- `max_gpu_core_clock_mhz` (integer, nullable) — Maximum graphics core clock in MHz (min: 0)
- `min_gpu_memory_clock_mhz` (integer, nullable) — Minimum graphics memory clock in MHz (min: 0)
- `max_gpu_memory_clock_mhz` (integer, nullable) — Maximum graphics memory clock in MHz (min: 0)
- `min_cpu_clock_mhz` (integer, nullable) — Minimum processor clock in MHz (min: 0)
- `max_cpu_clock_mhz` (integer, nullable) — Maximum processor clock in MHz (min: 0)
- `count` (integer, required) — Max number of results to return (min: 1; max: 3000)

## Response

### 200 — Successful Response

- `@type` (string) (default: "ThreedmarkResult")
- `id` (string, required)
- `url` (string, required)
- `test` (string, required)
- `test_name` (string, nullable)
- `test_code` (string, nullable)
- `rank` (integer, nullable)
- `uploaded_at` (integer, nullable)
- `user` (string, nullable)
- `user_id` (string, nullable)
- `country` (string, nullable)
- `cpu` (string, nullable)
- `gpu` (string, nullable)
- `gpu_count` (integer, nullable)
- `model` (string, nullable)
- `storage_model` (string, nullable)
- `device_type` (string, nullable)
- `status` (string, nullable)
- `max_clock_mhz` (integer, nullable)
- `gpu_core_clock_mhz` (integer, nullable)
- `gpu_memory_clock_mhz` (integer, nullable)
- `overall_score` (number, nullable)
- `graphics_score` (number, nullable)
- `physics_score` (number, nullable)
- `combined_score` (number, nullable)
- `average_fps` (number, nullable)
- `target_fps` (number, nullable)
- `scores` (object) (default: {})
  - `*` (number)

## Errors

### 422 — Validation Error

A filter was paired with a test that does not apply it, a score_type that test does not rank, or a country or drive model the source does not publish

What to do: Check the fields against this schema. A URN with the wrong prefix is the most common cause.

- `detail` (array)
  - `loc` (array, required)
  - `msg` (string, required)
  - `type` (string, required)
  - `input` (any)
  - `ctx` (object)

### 408

The request ran past its time limit

What to do: Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.

### 412

No submitted run matches that combination of test and filters, or the gpu, cpu or mac_model name matched nothing in the source's hardware catalogue

What to do: Retrying will not help: either the entity does not exist, or the input points at a different one.

### 429

Too many requests: a rate limit or a usage window is exhausted

What to do: When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.

### 500

Something broke on our side

What to do: Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.

### 529

Rate limit reached, or the endpoint is overloaded

What to do: Wait at least 30 seconds, then retry.

## Response envelope

Success: Array of objects (may be empty if no results)

Error: Error may coexist with partial results if it occurs mid-execution. Check X-Error header and status code.

Every response carries these headers:

- `X-Error` — Error message text (present only on error)
- `X-Request-ID` — Unique request identifier
- `X-Execution-Time` — Execution time in seconds
- `X-Result-Count` — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
- `X-Total-Available-Results` — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
- `X-Warning` — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
- `X-Retry-After` — Seconds to wait before retrying. Present only on 429.