/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

• @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 — 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 Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit 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 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 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 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 Wait at least 30 seconds, then retry.

Response 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.