QuantTrail API

Send a computer's hardware and what it is for. Get back the local AI models that run well on it, how much memory and context they need, and the commands to download them.

https://quanttrailpicker.com

Getting started

Introduction

The QuantTrail API answers one question: which local AI models run well on this machine, for this job, and how do I get them? It knows about 266 open models (Qwen, Gemma, Llama, Mistral, DeepSeek, Phi, Granite and more), their download sizes in every GGUF format, the memory each needs at a given context length, and where to download them.

You send hardware and a use. You get ranked models with memory estimates, where they run (GPU, unified memory, GPU and RAM, CPU or phone), expected speed, the largest context that fits and, if you ask, ready-made ollama pull and hf download commands. QuantTrail does not host or proxy model files.

Base URL	`https://quanttrailpicker.com`
Format	JSON in, JSON out. POST bodies must be `Content-Type: application/json`, up to 16,384 bytes
Authentication	Optional API key in `X-QuantTrail-Key` (authentication)
Versioning	`v1` changes are additive: new fields and routes, never removed or renamed ones
Machine-readable	OpenAPI 3.1

Most apps need one call: Get picks for a use. For filters (licenses, formats, families, speed) use Rank models. Building it into an app: the integration guide has detection scripts, a client and a checklist.

Quick start

curl -X POST https://quanttrailpicker.com/v1/picks \
  -H "Content-Type: application/json" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY" \
  -d '{
  "use": "coding",
  "hardware": {
    "platform": "windows",
    "ram_gb": 32,
    "gpu": "nvidia",
    "vram_gb": 12
  },
  "install": true,
  "store_device": false
}'

Authentication

Calls work without a key, within the anonymous limits. With a key, requests use your account level's limits instead. There are two credentials; do not mix them up.

Credential	Looks like	Opens	Send as
API key	`qt_u3f9a0c12b4d5_` and 40 hex characters	Every public `/v1` route, with your level's limits and model families	`X-QuantTrail-Key: <key>`, or `Authorization: Bearer <key>`
Session token	A Supabase Auth access token (JWT) from signing in	Your account routes: `/v1/me`, keys, saved computers, voting	`Authorization: Bearer <token>`

Get a key on the API page: sign in with a confirmed account, name the key, pick its model family, and copy it. It is shown once; QuantTrail keeps only a hash. If you lose it or it leaks, roll it: the old key stops working at once.

Keep keys on a machine you control: your server, a desktop app's local settings, a home server. Never in a web page, a browser bundle, a mobile app package or a public repository. Browser and phone clients should call your server, which calls QuantTrail.
A wrong, rolled or revoked key gets 401 invalid_key. It is not served anonymously instead, so a misconfigured app notices at once.
Keys do nothing on /v1/me routes. A stolen key cannot make keys or see the account.
Session tokens expire after about an hour; the website refreshes them. Scripts can sign in with @supabase/supabase-js using auth.url and auth.key from meta.

The operator's own applications use application keys with per-minute, per-day and allowance limits; refusals add 403 quota_exhausted.

Headers

POST /v1/picks HTTP/1.1
Host: quanttrailpicker.com
Content-Type: application/json
User-Agent: MyApp/1.0 (+https://example.com)
X-QuantTrail-Key: qt_u3f9a0c12b4d5_0f3c...

401 response

{
  "error": "invalid_key",
  "message": "This key is not valid. It may have been rolled or revoked."
}

Levels and limits

A key's limits come from its account's level, read on every request, so a level change applies at once. Live values come from plans; these are the current ones.

Level	Price	Keys	Requests a week	Requests a minute, per key	Model families per key
Free	0	1	1,000	10	1
Basic 5	5 USD a month	2	10,000	30	3
Basic 10	10 USD a month	3	50,000	60	all
Basic 15	15 USD a month	5	150,000	120	all
Basic Lifetime	250 USD once	10	no limit	120	all

Every level can use every filter, and every key can carry its own limits. Levels differ in keys, volume and families.
Weekly requests are counted across all of an account's keys, Monday 00:00 UTC to Sunday. Over: 429 weekly_limit.
Per minute is per key, in UTC calendar minutes. Over: 429 rate_limited with Retry-After.
Every /v1 request sent with a key counts, catalog reads included; /v1/me routes never do. Refused requests count too, so do not retry in a loop.
Model families: a Free or Basic 5 key sees only its families everywhere. Other models are left out of lists and answer 404. A key's families can change once every 7 days.
Paid levels are not on sale yet; the operator sets levels by hand.

Without a key, /v1/recommend, /v1/picks and /v1/requirements are limited per client address: a call less than 1 second after the previous one is held about 2 seconds, then answered. Every 10th early call starts a timeout (60 seconds, then 120, then 180) answered with 429 rate_limited and Retry-After. After 30 quiet minutes the client is forgotten.

Response headers with an account key

HTTP/1.1 200 OK
X-QuantTrail-App: u3f9a0c12b4d5
X-QuantTrail-Level: free
X-RateLimit-Remaining-Minute: 9
X-RateLimit-Remaining-Week: 874

429 response

{
  "error": "weekly_limit",
  "message": "The Free level allows 1,000 requests a week across your keys. The count starts again on Monday 00:00 UTC."
}

Key limits

Any key, on any level, can be limited to what one app needs. Set the limits on the API page (Limits for this key) or with Create a key and Update a key. Every request made with the key then sees only models and formats inside them, on every route: lists, picks, rankings, fit checks, requirements and model pages. A model outside them answers 404, and a candidate outside them comes back in unknown_candidates.

Limit	Keeps
`families`	Models in these families. Required on Free (1) and Basic 5 (up to 3), locked for 7 days after a change; optional elsewhere and changeable at any time
`family_kind`	`"brand"` keeps the general-purpose families, `"specialized"` the ones built for one job or size band (the `kind` in families)
`quants`	Only these formats. Other formats are not listed, ranked or estimated. A known (untracked) format is used when the request names it in `quants`
`tasks`	Models that support at least one of these tasks
`support_levels`	Models in these release-date levels
`origins`, `vendors`	Models from these origins or companies
`license: "permissive"`	Models with a permissive license
`allow_gated: false`	Models without a Hugging Face click-through

Limits combine with the request: a request can narrow further with its own filters, never widen. When a Free or Basic 5 account moves to a level without a family limit, the family its level forced stops applying and the key opens to every family; families chosen as a limit keep applying.

Limit a key to coding, two formats

{
  "families": [
    "qwen",
    "mistral"
  ],
  "limits": {
    "tasks": [
      "coding"
    ],
    "quants": [
      "Q4_K_M",
      "Q6_K"
    ],
    "license": "permissive"
  }
}

In the account summary

{
  "id": "u0a1b2c3d4e5f",
  "name": "Coding server",
  "families": [
    "qwen",
    "mistral"
  ],
  "limits": {
    "quants": [
      "Q4_K_M",
      "Q6_K"
    ],
    "tasks": [
      "coding"
    ],
    "license": "permissive"
  }
}

Errors

Errors are JSON with a stable error code. field names the request field to fix; message explains in plain English.

Status	error	Meaning
400	`invalid_request`	A field is wrong, unknown, missing or duplicated. Unknown fields are refused on purpose. Fix it; do not retry unchanged
401	`invalid_key`	Key malformed, rolled or revoked
401	`sign_in_required`	Account route without a valid session token
403	`quota_exhausted`	Application key allowance used up
404	`not_found`	Unknown route, hidden model, or a model outside your key's families
405	`method_not_allowed`	Wrong method (HEAD included)
409	`key_limit`, `preset_limit`	Too many keys or saved computers
410	`gone`	Retired route
413	`payload_too_large`	Body over 16,384 bytes
415	`unsupported_media_type`	POST without `Content-Type: application/json`
429	`rate_limited`	Too fast; wait `Retry-After` seconds
429	`weekly_limit`	Weekly requests used; resets Monday 00:00 UTC
429	`families_locked`, `vote_locked`	Changed too recently; `message` says when it opens
500	`internal_error`	Server fault; retry later with backoff
503	`sign_in_unavailable`, `plans_unavailable`, `votes_disabled`	A dependency is down or a feature is off

A 403 with an HTML body reading "error code: 1010" comes from Cloudflare, not the API: your HTTP library's default User-Agent was refused (Python's urllib is one). Send your own User-Agent.

CORS and caching

CORS is open to every origin on /v1: methods GET, POST, OPTIONS; request headers Content-Type, Authorization, X-QuantTrail-Key.
Browsers can read X-QuantTrail-App, X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day, X-Quota-Remaining and Retry-After. Server code can read every header.
Recommendations, votes and account routes are no-store. Hardware lookups, survey and highlights cache up to 5 minutes; other catalog GETs up to an hour. POST answers and errors never cache.
An answer only changes when the catalog changes (updated_at in meta, a few times a day) or the hardware does. Caching each answer for an hour per machine is plenty.

Privacy

Requests, hardware and addresses are not stored or logged, with two exceptions the caller controls:

Phone and board survey. When hardware.device_model names a phone, tablet or board and store_device is not false, the model name as sent, the RAM and the hardware class are kept for review (at most three per client session) and survey.message thanks the caller. Desktops are never recorded. Send store_device: false unless your users agreed.
Saved computers, only when a signed-in account saves one.

Votes keep only the hardware class. Keys are stored as hashes. The rate limiter names its counter with a hash of the address.

Objects

The hardware object

Every recommendation route takes the same hardware object. Send everything you know: each field improves the answer, and hardware_resolved.estimate.notes says what was assumed. What you send always wins over a matched device, then a matched chip, then memory type and speed.

Required: platform and ram_gb, unless tier or a device_model found in devices is sent.

Fields

tierstring

A hardware class: low, mid, high or max (tiers). Fills every field from a preset; use it when the user does not know their hardware.

platformstring

Operating system. Required unless tier or a known device_model is sent.

One of windows macos linux android ios.

ram_gbnumber

Installed system RAM in GB (the marketed size: 32, not 31.7). Required unless tier or a known device_model is sent.

From 1 to 2048.

cpu_coresinteger

Logical processors. Fewer than 6 slows CPU speed estimates one step.

From 1 to 512.

gpu_namestring

Graphics card name or WebGL renderer string. A match in GPUs fills gpu and vram_gb you did not send. An unknown name without vram_gb counts as no GPU, with a hint.

gpustring

Kind of the strongest graphics adapter. apple requires macos. unified is a shared-memory PC (AMD Strix Halo, NVIDIA DGX Spark and similar).

One of none integrated nvidia amd intel apple unified. Default "none".

vram_gbnumber

Dedicated video memory. Used only for nvidia, amd and intel; 90% of it is the GPU budget.

From 0 to 1024. Default 0.

disk_free_gbnumber

Free space where models will be stored. Larger downloads are dropped (insufficient_disk).

From 0 to 100000.

memory_bandwidth_gbpsnumber

System memory bandwidth in GB/s. Gives a tokens-per-second estimate for CPU and phone fits. Beats every memory field below.

From 1 to 2000.

device_modelstring

Phone, tablet or board name or model code (Galaxy S24, SM-S928B, Raspberry Pi 5). A match in devices fills platform, RAM (its smallest option), cores and bandwidth you did not send.

chipstring

Chip name (Snapdragon 8 Gen 3, Apple A18 Pro). A match in chips fills cores and bandwidth you did not send.

memory_typestring

Memory type. With memory_speed_mts and memory_bus_bits it gives the bandwidth when no device or chip did.

One of ddr3 ddr4 ddr5 lpddr3 lpddr4 lpddr4x lpddr5 lpddr5x.

memory_speed_mtsnumber

Memory transfer rate in MT/s, for example 6000. A typical speed for memory_type is assumed when missing.

From 400 to 20000.

memory_bus_bitsinteger

Memory bus width. Assumed 128 for DDR (two channels), 64 for LPDDR and phones.

From 16 to 1024.

A desktop, fully described

{
  "platform": "windows",
  "ram_gb": 32,
  "cpu_cores": 16,
  "gpu": "nvidia",
  "gpu_name": "NVIDIA GeForce RTX 4070",
  "vram_gb": 12,
  "disk_free_gb": 200,
  "memory_type": "ddr5",
  "memory_speed_mts": 6000
}

A phone by model code

{
  "device_model": "SM-S928B"
}

Unknown machine

{
  "tier": "mid"
}

The preferences object

Filters for Rank models and Hardware requirements. Every level may use every filter. If a list comes back empty, excluded counts the models each filter removed: task, context, license, family, vendor, origin, support, insufficient_memory, insufficient_disk, too_large, too_slow, below_smartness_min, not_in_candidates.

Fields

smartness_minnumber

Drops formats whose smartness (model score minus the format penalty) is below this.

From 1 to 10. Default 1.

size_max_gbnumber

Drops formats with a larger download.

From above 0 to 100000.

prioritystring

Ranking weights: balanced 50% smartness, 30% speed; quality 70/15; speed 30/55; small puts 40% on a small download. See ranking.

One of balanced quality speed small. Default "balanced".

min_speedstring

Drops formats slower than this.

One of fast moderate slow very_slow. Default "slow".

tasksarray of strings

Task ids from meta (chat, coding, reasoning, vision, tool_use, multilingual). A model must support every listed task.

Default ["chat"].

context_tokensinteger

Context length to plan memory for. Models with a smaller window are dropped.

From 512 to 2000000. Default 8192.

originsarray of strings

Vendor origins to keep: china, usa, other.

Default [].

families_includearray of strings

Only these model families (families).

Default [].

families_excludearray of strings

Leave out these model families.

Default [].

family_kindstring

brand keeps the general-purpose families (Gemma, Qwen, Llama); specialized keeps the families built for one job or one size band (code completion, small devices). The kind of each family is in families.

One of any brand specialized. Default "any".

vendors_includearray of strings

Only these companies (vendors).

Default [].

vendors_excludearray of strings

Leave out these companies.

Default [].

licensestring

permissive keeps Apache, MIT and similar licenses.

One of any permissive. Default "any".

allow_gatedboolean

false drops models that need a license click-through on Hugging Face.

Default true.

quant_minstring

The lowest tracked format to consider, by quality order from formats. The default leaves out IQ2_M, Q3_K_M and IQ4_XS; send IQ2_M for small machines.

Default "Q4_K_M".

support_levelsarray of strings

Release-date levels from meta: current, limited_1, limited_b2, limited_b1, limited_a2, limited_a1. Empty means all.

Default [].

quantsarray of strings

Exact formats to consider, any tracked or known id from formats. Replaces quant_min. Known formats are estimated where the file was not seen.

Default [].

Commercial app, new models, fast

{
  "tasks": [
    "coding"
  ],
  "license": "permissive",
  "allow_gated": false,
  "support_levels": [
    "current"
  ],
  "priority": "speed",
  "min_speed": "moderate",
  "quants": [
    "Q4_K_M",
    "Q5_K_M",
    "Q6_K"
  ]
}

The recommendation object

Each item in reasoning, speed, recommendations, popular and cpu_recommendations.

Fields

rankinteger

1 is the best in its list.

id, namestring

Catalog id and display name.

family, generation, vendor, vendor_name, origin, countrystring

Where the model comes from.

quantstring

The chosen format, for example Q4_K_M.

formatobject

id, label ("Balanced"), quality_level (1 to 5), size_pct, compression_pct, description.

params_bnumber

Billions of parameters.

file_gb, size_sourcenumber, string

Download size and whether it was measured from the repository or estimated.

est_memory_gbnumber

Memory needed at the requested context: weights x 1.05, plus context, plus 0.5 GB (0.6 GB more for vision).

memory_breakdownobject

weights_gb, context_gb, overhead_gb.

max_context_tokensinteger

The most context that still fits the same memory, rounded down to 1,024. Use it for llama.cpp -c or Ollama num_ctx.

fitstring

gpu (all on the graphics card), unified (Apple or shared memory), split (GPU and system RAM), cpu or mobile.

One of gpu unified split cpu mobile.

speedstring

Expected generation speed class.

One of fast moderate slow very_slow.

est_tokens_per_secondnumber or null

Estimated from memory bandwidth for CPU and phone fits; null otherwise.

smartness, effective_smartness, scorenumber

Heuristic quality (1 to 10), after the format penalty, and the ranking score (0 to 100).

tasks, context_tokens, license, gatedmixed

What the model is for, its window, its license and whether Hugging Face asks for a click-through.

supportobject

{id, label, limited}: the release-date level.

min_tierstring

The lowest hardware class that runs it (Q4_K_M, slow or better).

votes, vote_nudgeobject, number

Votes from accounts with the same hardware class, and the points they add or take (up to 5).

downloadsinteger

Hugging Face downloads, last 30 days.

reasons, warningsarray of strings

Plain-English notes. Show warnings to the user.

linksobject

huggingface, gguf, ollama addresses.

installobject

Only with install: true. See the install object.

Example

{
  "rank": 1,
  "id": "qwen3.5-9b",
  "name": "Qwen3.5-9B",
  "family": "qwen",
  "vendor": "alibaba",
  "vendor_name": "Alibaba",
  "origin": "china",
  "quant": "Q6_K",
  "format": {
    "id": "Q6_K",
    "label": "Very high",
    "quality_level": 4,
    "size_pct": 41,
    "compression_pct": 59
  },
  "params_b": 9.65,
  "file_gb": 7.91,
  "size_source": "measured",
  "est_memory_gb": 10.9,
  "memory_breakdown": {
    "weights_gb": 8.31,
    "context_gb": 2.08,
    "overhead_gb": 0.5
  },
  "max_context_tokens": 40960,
  "fit": "split",
  "speed": "moderate",
  "est_tokens_per_second": null,
  "smartness": 7.2,
  "effective_smartness": 7.15,
  "score": 71.4,
  "tasks": [
    "chat",
    "reasoning",
    "tool_use",
    "multilingual"
  ],
  "context_tokens": 262144,
  "license": "apache-2.0",
  "gated": false,
  "support": {
    "id": "current",
    "label": "Current",
    "limited": false
  },
  "min_tier": "mid",
  "reasons": [
    "Uses split memory",
    "Very high (Q6_K)",
    "Supports chat"
  ],
  "warnings": [
    "Uses system RAM; generation can be slower."
  ],
  "links": {
    "huggingface": "https://huggingface.co/Qwen/Qwen3.5-9B",
    "gguf": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF",
    "ollama": "qwen3.5:9b"
  }
}

The install object

Added to each item when the request has install: true.

ollama is null when Ollama has no tag. Ollama picks its own format for a tag (usually Q4_K_M), which may differ from quant.
gguf is null without a GGUF repository. file, file_url and curl are null until the repository has been listed; cli always works (pip install -U huggingface_hub) and fetches every part of a split file (parts above 1).
Gated models need the license accepted on Hugging Face and HF_TOKEN set where the download runs.
Every command works in Windows cmd, PowerShell and Linux or macOS shells.

Example

{
  "name": "Qwen3.5-9B",
  "ollama": {
    "tag": "qwen3.5:9b",
    "pull": "ollama pull qwen3.5:9b",
    "run": "ollama run qwen3.5:9b",
    "url": "https://ollama.com/library/qwen3.5:9b"
  },
  "huggingface": {
    "repo": "Qwen/Qwen3.5-9B",
    "url": "https://huggingface.co/Qwen/Qwen3.5-9B"
  },
  "gguf": {
    "repo": "unsloth/Qwen3.5-9B-GGUF",
    "url": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF",
    "quant": "Q6_K",
    "file": "Qwen3.5-9B-Q6_K.gguf",
    "parts": 1,
    "file_url": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q6_K.gguf",
    "cli": "hf download unsloth/Qwen3.5-9B-GGUF --include \"*Q6_K*.gguf\" --local-dir \"models/Qwen3.5-9B\"",
    "curl": "curl -L -o \"Qwen3.5-9B-Q6_K.gguf\" \"https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q6_K.gguf\""
  }
}

How ranking works

For each model, every allowed format is checked against the hardware budgets; the best-scoring format represents the model, and models are sorted by score.

Machine	GPU budget	System budget
Discrete GPU (`nvidia`, `amd`, `intel` with VRAM)	90% of VRAM	RAM minus 25% for the OS (3 to 8 GB)
Mac (`apple`) or `unified` PC	70% of RAM (75% from 36 GB)	none
No discrete GPU	none	RAM minus 25% for the OS (3 to 8 GB)
Android, iOS	none	40%, 35% of RAM

fit	When	speed
`gpu`	Fits the GPU budget	fast
`unified`	Fits the unified budget	Apple: to 8B fast, to 32B moderate, else slow. Other: to 8B moderate, else slow
`split`	Fits GPU plus system	moderate if the GPU holds 60% or more, else slow
`cpu`, `mobile`	Fits system memory	From bandwidth: tokens/s = bandwidth x 0.5 / file size (20 fast, 8 moderate, 3 slow). Without it, by size and cores

priority	Smartness	Speed	Small download	Recent	Headroom
`balanced`	50%	30%	5%	10%	5%
`quality`	70%	15%	0%	10%	5%
`speed`	30%	55%	5%	5%	5%
`small`	30%	20%	40%	5%	5%

Votes from accounts with the same hardware class add or take up to 5 points. Smartness is a heuristic from size, generation and published scores; speeds are estimates, not benchmarks on your machine.

Recommendations

Get picks for a use

POST/v1/picks

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits; without a key, the anonymous hold.

The call most apps need. Returns two ranked lists for one use: reasoning, the smartest models that fit, and speed, the fastest that fit (moderate speed or better when possible). The same model can be in both.

Picks use fixed profiles and take no filters; use Rank models for those. They leave out base models whose instruct version is listed, re-quantized copies without a GGUF or Ollama download, and CPU-only fallbacks. dnd_dm keeps general chat models of 3B or more.

GET works too, with flat names: /v1/picks?use=chat&platform=windows&ram_gb=16&gpu=nvidia&vram_gb=8&install=true&store_device=false.

Body parameters

hardwareobjectRequired

usestringRequired

The job: coding, chat or dnd_dm. The operator can add uses; a wrong value lists the current ones.

context_tokensinteger

Context length to plan for. Defaults per use: coding 16384, chat 8192, dnd_dm 16384.

From 512 to 2000000.

limitinteger

Items per list.

From 1 to 10. Default 3.

installboolean

Add an install object with Ollama and Hugging Face download commands to each item.

Default false.

store_deviceboolean

Phone and board survey. When device_model names a phone, tablet or board, its name, RAM and class are kept for review unless this is false. Desktops are never recorded. See privacy.

Default true.

Returns

use, profile, context_tokens, and two lists of recommendation objects, plus:

reasoningarray

Up to limit models, smartest first.

speedarray

Up to limit models, fastest first.

profileobject

label, tasks, min_params_b of the use.

hardware_resolvedobject

The machine as understood: every hardware field, tier, gpu_budget_gb, system_budget_gb and estimate {device, chip, bandwidth_source, notes}. Show notes to the user; they say what was matched and assumed.

capacityobject

fast (GPU or unified budget) and total budgets with the largest model, in billions of parameters, that fits at Q4 and Q8.

hintsarray of strings

Why a list is empty or degraded. Show them.

catalogobject

updated_at and model_count.

surveyobject or null

null unless a phone or board device_model was sent; then {stored, message}.

Errors

`400 invalid_request`	A field is wrong, unknown or missing; `field` names it.
`413 payload_too_large`	Body over 16,384 bytes.
`415 unsupported_media_type`	Send `Content-Type: application/json`.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl -X POST "https://quanttrailpicker.com/v1/picks" \
  -H "Content-Type: application/json" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY" \
  -d '{
  "use": "chat",
  "hardware": {
    "platform": "windows",
    "ram_gb": 16,
    "gpu": "nvidia",
    "vram_gb": 8
  },
  "limit": 1,
  "install": true,
  "store_device": false
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/picks",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    json={
        "use": "chat",
        "hardware": {
            "platform": "windows",
            "ram_gb": 16,
            "gpu": "nvidia",
            "vram_gb": 8,
        },
        "limit": 1,
        "install": True,
        "store_device": False,
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/picks', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
  body: JSON.stringify({
    "use": "chat",
    "hardware": {
      "platform": "windows",
      "ram_gb": 16,
      "gpu": "nvidia",
      "vram_gb": 8
    },
    "limit": 1,
    "install": true,
    "store_device": false
  }),
});
const data = await res.json();

Response

{
  "use": "chat",
  "profile": {
    "label": "Chatbot",
    "tasks": [
      "chat"
    ],
    "min_params_b": 0
  },
  "context_tokens": 8192,
  "catalog": {
    "updated_at": "2026-10-12T02:01:17.074Z",
    "model_count": 266
  },
  "hardware_resolved": {
    "platform": "windows",
    "ram_gb": 16,
    "gpu": "nvidia",
    "vram_gb": 8,
    "tier": "mid",
    "gpu_budget_gb": 7.2,
    "system_budget_gb": 12,
    "estimate": {
      "device": null,
      "chip": null,
      "bandwidth_source": null,
      "notes": []
    }
  },
  "reasoning": [
    {
      "rank": 1,
      "id": "qwen3.5-9b",
      "name": "Qwen3.5-9B",
      "family": "qwen",
      "vendor": "alibaba",
      "vendor_name": "Alibaba",
      "origin": "china",
      "quant": "Q6_K",
      "format": {
        "id": "Q6_K",
        "label": "Very high",
        "quality_level": 4,
        "size_pct": 41,
        "compression_pct": 59
      },
      "params_b": 9.65,
      "file_gb": 7.91,
      "size_source": "measured",
      "est_memory_gb": 10.9,
      "memory_breakdown": {
        "weights_gb": 8.31,
        "context_gb": 2.08,
        "overhead_gb": 0.5
      },
      "max_context_tokens": 40960,
      "fit": "split",
      "speed": "moderate",
      "est_tokens_per_second": null,
      "smartness": 7.2,
      "effective_smartness": 7.15,
      "score": 71.4,
      "tasks": [
        "chat",
        "reasoning",
        "tool_use",
        "multilingual"
      ],
      "context_tokens": 262144,
      "license": "apache-2.0",
      "gated": false,
      "support": {
        "id": "current",
        "label": "Current",
        "limited": false
      },
      "min_tier": "mid",
      "reasons": [
        "Uses split memory",
        "Very high (Q6_K)",
        "Supports chat"
      ],
      "warnings": [
        "Uses system RAM; generation can be slower."
      ],
      "links": {
        "huggingface": "https://huggingface.co/Qwen/Qwen3.5-9B",
        "gguf": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF",
        "ollama": "qwen3.5:9b"
      },
      "install": {
        "name": "Qwen3.5-9B",
        "ollama": {
          "tag": "qwen3.5:9b",
          "pull": "ollama pull qwen3.5:9b",
          "run": "ollama run qwen3.5:9b",
          "url": "https://ollama.com/library/qwen3.5:9b"
        },
        "huggingface": {
          "repo": "Qwen/Qwen3.5-9B",
          "url": "https://huggingface.co/Qwen/Qwen3.5-9B"
        },
        "gguf": {
          "repo": "unsloth/Qwen3.5-9B-GGUF",
          "url": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF",
          "quant": "Q6_K",
          "file": "Qwen3.5-9B-Q6_K.gguf",
          "parts": 1,
          "file_url": "https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q6_K.gguf",
          "cli": "hf download unsloth/Qwen3.5-9B-GGUF --include \"*Q6_K*.gguf\" --local-dir \"models/Qwen3.5-9B\"",
          "curl": "curl -L -o \"Qwen3.5-9B-Q6_K.gguf\" \"https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q6_K.gguf\""
        }
      }
    }
  ],
  "speed": [
    "..."
  ],
  "hints": [],
  "survey": null
}

Rank models

POST/v1/recommend

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits; without a key, the anonymous hold.

One ranked list with every filter: tasks, priority, speed, formats, licenses, families, vendors, origins and release levels. Also returns the same models by downloads, CPU-only results, and how many models each filter removed.

GET takes every hardware and preference field flat, arrays comma-separated: /v1/recommend?platform=linux&ram_gb=64&gpu=nvidia&vram_gb=24&tasks=coding&quants=Q4_K_M,Q6_K&limit=3.

Body parameters

hardwareobjectRequired

preferencesobject

candidatesarray of strings

Only these models. Matches a catalog id, a Hugging Face repo or an Ollama tag (qwen3:8b). Unmatched names come back in unknown_candidates.

Default [].

include_cpuboolean

Add cpu_recommendations, the same search with the GPU ignored, when a discrete GPU is present.

Default true.

detectedarray of strings

Which of platform, cpu_cores, ram_gb, gpu your app detected rather than the user typed. Accepted; it does not change the ranking.

One of platform cpu_cores ram_gb gpu. Default [].

limitinteger

Items per list.

From 1 to 25. Default 5.

installboolean

Add an install object with Ollama and Hugging Face download commands to each item.

Default false.

store_deviceboolean

Phone and board survey. When device_model names a phone, tablet or board, its name, RAM and class are kept for review unless this is false. Desktops are never recorded. See privacy.

Default true.

Returns

Lists of recommendation objects, plus:

recommendationsarray

By score.

populararray

The same models by downloads.

cpu_recommendationsarray or null

The same search with the GPU ignored; null without a discrete GPU or with include_cpu: false.

excludedobject

Models removed per filter, for example {"task": 213, "license": 6}.

unknown_candidatesarray of strings

candidates that matched nothing.

hardware_resolvedobject

capacityobject

fast (GPU or unified budget) and total budgets with the largest model, in billions of parameters, that fits at Q4 and Q8.

hintsarray of strings

Why a list is empty or degraded. Show them.

catalogobject

updated_at and model_count.

surveyobject or null

null unless a phone or board device_model was sent; then {stored, message}.

Errors

`400 invalid_request`	A field is wrong, unknown or missing; `field` names it.
`413 payload_too_large`	Body over 16,384 bytes.
`415 unsupported_media_type`	Send `Content-Type: application/json`.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl -X POST "https://quanttrailpicker.com/v1/recommend" \
  -H "Content-Type: application/json" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY" \
  -d '{
  "hardware": {
    "platform": "linux",
    "ram_gb": 64,
    "gpu": "nvidia",
    "vram_gb": 24
  },
  "preferences": {
    "tasks": [
      "coding"
    ],
    "priority": "quality",
    "context_tokens": 32768,
    "license": "permissive"
  },
  "limit": 3,
  "store_device": false
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/recommend",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    json={
        "hardware": {
            "platform": "linux",
            "ram_gb": 64,
            "gpu": "nvidia",
            "vram_gb": 24,
        },
        "preferences": {
            "tasks": ["coding"],
            "priority": "quality",
            "context_tokens": 32768,
            "license": "permissive",
        },
        "limit": 3,
        "store_device": False,
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/recommend', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
  body: JSON.stringify({
    "hardware": {
      "platform": "linux",
      "ram_gb": 64,
      "gpu": "nvidia",
      "vram_gb": 24
    },
    "preferences": {
      "tasks": [
        "coding"
      ],
      "priority": "quality",
      "context_tokens": 32768,
      "license": "permissive"
    },
    "limit": 3,
    "store_device": false
  }),
});
const data = await res.json();

Response

{
  "catalog": {
    "updated_at": "2026-10-12T02:01:17.074Z",
    "model_count": 266
  },
  "hardware_resolved": {
    "platform": "linux",
    "ram_gb": 64,
    "gpu": "nvidia",
    "vram_gb": 24,
    "tier": "max",
    "gpu_budget_gb": 21.6,
    "system_budget_gb": 56
  },
  "capacity": {
    "context_tokens": 32768,
    "fast": {
      "budget_gb": 21.6,
      "max_params_b_q4": 23.1,
      "max_params_b_q8": 13.6
    },
    "total": {
      "budget_gb": 77.6,
      "max_params_b_q4": 88.4,
      "max_params_b_q8": 52.1
    }
  },
  "recommendations": [
    {
      "rank": 1,
      "id": "qwen3-coder-next",
      "quant": "Q5_K_M",
      "fit": "split",
      "speed": "slow",
      "score": 79.1,
      "max_context_tokens": 32768,
      "...": "..."
    }
  ],
  "popular": [
    "..."
  ],
  "cpu_recommendations": [
    "..."
  ],
  "excluded": {
    "context": 19,
    "license": 6,
    "task": 213,
    "insufficient_memory": 1
  },
  "unknown_candidates": [],
  "hints": [],
  "survey": null
}

Check one model

POST/v1/models/{id}/fit

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Will this model run here, and in which format? Returns every format of one model on the given hardware, with memory, where it runs, speed and the context that fits, and the format the ranking would choose.

Path parameters

idstringRequired

Catalog model id, from list models.

Body parameters

hardwareobjectRequired

A hardware object.

context_tokensinteger

Context to plan for.

From 512 to 2000000. Default 8192.

Returns

model, context_tokens, hardware_resolved, and:

recommendedstring or null

The format the ranking would choose.

notesarray of strings

Plain-English summary.

formatsarray

One per tracked format: quant, label, quality_level, file_gb, est_memory_gb, fit (or none), speed, est_tokens_per_second, est_words_per_second, max_context_tokens, short_by_gb (0 when it fits), install.

Errors

`400 invalid_request`	A field is wrong, unknown or missing; `field` names it.
`413 payload_too_large`	Body over 16,384 bytes.
`415 unsupported_media_type`	Send `Content-Type: application/json`.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.
`404 not_found`	No such model, or outside your key's families.

curl -X POST "https://quanttrailpicker.com/v1/models/qwen3-8b/fit" \
  -H "Content-Type: application/json" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY" \
  -d '{
  "hardware": {
    "platform": "windows",
    "ram_gb": 16,
    "gpu": "nvidia",
    "vram_gb": 8
  },
  "context_tokens": 8192
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/models/qwen3-8b/fit",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    json={
        "hardware": {
            "platform": "windows",
            "ram_gb": 16,
            "gpu": "nvidia",
            "vram_gb": 8,
        },
        "context_tokens": 8192,
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/models/qwen3-8b/fit', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
  body: JSON.stringify({
    "hardware": {
      "platform": "windows",
      "ram_gb": 16,
      "gpu": "nvidia",
      "vram_gb": 8
    },
    "context_tokens": 8192
  }),
});
const data = await res.json();

Response

{
  "model": "qwen3-8b",
  "context_tokens": 8192,
  "hardware_resolved": {
    "platform": "windows",
    "ram_gb": 16,
    "gpu": "nvidia",
    "vram_gb": 8,
    "tier": "mid",
    "gpu_budget_gb": 7.2,
    "system_budget_gb": 12,
    "estimate": {
      "device": null,
      "chip": null,
      "bandwidth_source": null,
      "notes": []
    }
  },
  "recommended": "Q4_K_M",
  "notes": [],
  "formats": [
    {
      "quant": "Q4_K_M",
      "label": "Balanced",
      "quality_level": 3,
      "file_gb": 5.03,
      "est_memory_gb": 6.44,
      "fit": "gpu",
      "speed": "fast",
      "est_tokens_per_second": null,
      "max_context_tokens": 17408,
      "short_by_gb": 0,
      "install": "..."
    },
    {
      "quant": "Q6_K",
      "label": "Very high",
      "quality_level": 4,
      "file_gb": 6.73,
      "est_memory_gb": 8.22,
      "fit": "split",
      "speed": "moderate",
      "max_context_tokens": 40960,
      "short_by_gb": 0,
      "install": "..."
    }
  ]
}

Hardware requirements

POST/v1/requirements

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits; without a key, the anonymous hold.

The reverse question: what hardware does a model, or a set of preferences, need? Send exactly one of models or preferences.

Body parameters

modelsarray of strings

Catalog model ids. Unknown ids come back in unknown_models. Send models or preferences, not both.

Default [].

preferencesobject

A preferences object. Send models or preferences, not both.

context_tokensinteger

Context length to plan memory for. Models with a smaller window are dropped.

From 512 to 2000000. Default 8192.

limitinteger

Items per list.

From 1 to 25. Default 5.

Returns

catalog, and:

modelsarray

Each model with variants: quant, file_gb, est_memory_gb, min_vram_gb, min_ram_gb_cpu_only, min_unified_ram_gb (null when no common size is enough).

minimum_hardwareobject

For the first model at Q4_K_M: vram_gb, ram_gb_cpu_only, unified_ram_gb, disk_gb.

unknown_modelsarray of strings

Ids that matched nothing.

Errors

`400 invalid_request`	A field is wrong, unknown or missing; `field` names it.
`413 payload_too_large`	Body over 16,384 bytes.
`415 unsupported_media_type`	Send `Content-Type: application/json`.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl -X POST "https://quanttrailpicker.com/v1/requirements" \
  -H "Content-Type: application/json" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY" \
  -d '{
  "models": [
    "qwen3-8b"
  ],
  "context_tokens": 8192
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/requirements",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    json={
        "models": ["qwen3-8b"],
        "context_tokens": 8192,
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/requirements', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
  body: JSON.stringify({
    "models": [
      "qwen3-8b"
    ],
    "context_tokens": 8192
  }),
});
const data = await res.json();

Response

{
  "catalog": {
    "updated_at": "2026-10-12T02:01:17.074Z",
    "model_count": 266
  },
  "models": [
    {
      "id": "qwen3-8b",
      "name": "Qwen3-8B",
      "smartness": 6.5,
      "variants": [
        {
          "quant": "Q4_K_M",
          "file_gb": 5.03,
          "est_memory_gb": 6.44,
          "min_vram_gb": 8,
          "min_ram_gb_cpu_only": 16,
          "min_unified_ram_gb": 16
        }
      ]
    }
  ],
  "minimum_hardware": {
    "model": "qwen3-8b",
    "quant": "Q4_K_M",
    "vram_gb": 8,
    "ram_gb_cpu_only": 16,
    "unified_ram_gb": 16,
    "disk_gb": 5.03
  },
  "unknown_models": []
}

Catalog

List models

GET/v1/models

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Every active model with its formats. Filters combine.

Query parameters

familystring

Family id (families).

generationstring

Generation label.

vendorstring

Vendor id (vendors).

originstring

china, usa or other.

taskstring

Task id.

qstring

Text in the id or name.

include_retiredstring

1 adds retired models.

Returns

{catalog, models}. Each model: id, name, family, generation, vendor, vendor_name, origin, country, hf_repo, gguf_repo, ollama, params_b, downloads, likes, released_at, support, papers, base_model, context_tokens, license, license_class, gated, tasks, smartness, min_tier, status and variants (quant_id, file_gb, size_source, file_name, file_parts).

Errors

`400 invalid_request`	Unknown filter.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/models?family=qwen&task=coding" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/models?family=qwen&task=coding",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/models?family=qwen&task=coding', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "catalog": {
    "updated_at": "2026-10-12T02:01:17.074Z",
    "model_count": 266
  },
  "models": [
    {
      "id": "qwen2.5-coder-7b-instruct",
      "name": "Qwen2.5-Coder-7B-Instruct",
      "family": "qwen",
      "vendor": "alibaba",
      "...": "...",
      "variants": [
        "..."
      ]
    }
  ]
}

Get a model

GET/v1/models/{id}

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

One model with every format and a links block for further reading.

Path parameters

idstringRequired

Catalog model id.

Returns

The model fields from list models, plus links: model_card, files, discussions, vendor, gguf, ollama, papers, base_model, demos.

Errors

`404 not_found`	No such model, hidden, or outside your key's families.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/models/qwen3-8b" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/models/qwen3-8b",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/models/qwen3-8b', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "id": "qwen3-8b",
  "name": "Qwen3-8B",
  "family": "qwen",
  "generation": "Qwen 3",
  "vendor": "alibaba",
  "vendor_name": "Alibaba",
  "origin": "china",
  "country": "CN",
  "hf_repo": "Qwen/Qwen3-8B",
  "gguf_repo": "Qwen/Qwen3-8B-GGUF",
  "ollama": "qwen3:8b",
  "params_b": 8.19,
  "downloads": 10146765,
  "likes": 2080,
  "released_at": "2025-04-27T03:42:21.000Z",
  "support": {
    "id": "limited_1",
    "label": "Limited 1",
    "limited": true
  },
  "context_tokens": 40960,
  "license": "apache-2.0",
  "license_class": "permissive",
  "gated": false,
  "tasks": [
    "chat",
    "reasoning",
    "tool_use",
    "multilingual"
  ],
  "smartness": 6.5,
  "min_tier": "mid",
  "variants": [
    {
      "quant_id": "Q4_K_M",
      "file_gb": 5.03,
      "size_source": "measured",
      "file_name": "Qwen3-8B-Q4_K_M.gguf",
      "file_parts": 1
    }
  ],
  "status": "active",
  "links": {
    "model_card": "https://huggingface.co/Qwen/Qwen3-8B",
    "gguf": "https://huggingface.co/Qwen/Qwen3-8B-GGUF",
    "ollama": "https://ollama.com/library/qwen3:8b",
    "...": "..."
  }
}

List families

GET/v1/families

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Model families with their vendor and active model count. Family ids are what keys are opened to and what families_include takes.

Returns

An array: id, label, vendor, kind (brand or specialized), default_context, generations, model_count.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/families" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/families",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/families', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

[
  {
    "id": "qwen",
    "label": "Qwen",
    "vendor": "alibaba",
    "kind": "brand",
    "default_context": 32768,
    "model_count": 98,
    "generations": [
      "..."
    ]
  }
]

List vendors

GET/v1/vendors

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Companies with country, origin and active model count.

Returns

An array: id, name, country, origin, model_count.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/vendors" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/vendors",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/vendors', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

[
  {
    "id": "alibaba",
    "name": "Alibaba",
    "country": "CN",
    "origin": "china",
    "model_count": 124
  }
]

List formats

GET/v1/formats

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

GGUF formats. tracked formats are used by default; known ones only when named in quants. position orders them by quality for quant_min.

Returns

An array: id, label, quality_level, description, bits_per_weight, smartness_penalty, position, status, size_pct, compression_pct.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/formats" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/formats",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/formats', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

[
  {
    "id": "Q4_K_M",
    "label": "Balanced",
    "quality_level": 3,
    "description": "The usual choice. About a third of full size, small quality loss.",
    "bits_per_weight": 4.92,
    "smartness_penalty": 0.3,
    "position": 24,
    "status": "tracked",
    "size_pct": 30.75,
    "compression_pct": 69.25
  }
]

Get metadata

GET/v1/meta

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Catalog freshness and every option list, for building forms. Check updated_at to know when cached answers are stale.

Returns

updated_at, model_count, active_models, retired_models, tasks, origins, quantizations (tracked), tiers, support_levels (id, label, before), platforms, gpu_kinds, vote_thresholds, auth (url, key for Supabase sign-in, or null).

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/meta" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/meta",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/meta', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "updated_at": "2026-10-12T02:01:17.074Z",
  "model_count": 266,
  "active_models": 266,
  "retired_models": 0,
  "tasks": [
    {
      "id": "chat",
      "label": "chat",
      "position": 0
    }
  ],
  "origins": [
    {
      "id": "china",
      "label": "China",
      "position": 1
    }
  ],
  "quantizations": [
    "..."
  ],
  "tiers": [
    "low",
    "mid",
    "high",
    "max"
  ],
  "support_levels": [
    {
      "id": "current",
      "label": "Current",
      "before": null
    }
  ],
  "platforms": [
    "windows",
    "macos",
    "linux",
    "android",
    "ios"
  ],
  "gpu_kinds": [
    "none",
    "integrated",
    "nvidia",
    "amd",
    "intel",
    "apple",
    "unified"
  ],
  "auth": {
    "url": "https://<project>.supabase.co",
    "key": "sb_publishable_..."
  }
}

Top models by size class

GET/v1/top-models

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The strongest models for five size classes, from phone to 128 GB, for chat and coding, ranked as a search would.

Returns

catalog_updated_at, uses, and classes: each with id, label, hardware and lists per use (rank, id, name, vendor_name, params_b, quant, file_gb, fit, speed, context_tokens, released_at, license, links).

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/top-models" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/top-models",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/top-models', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "catalog_updated_at": "2026-10-12T02:01:17.074Z",
  "uses": [
    "chat",
    "coding"
  ],
  "classes": [
    {
      "id": "phone",
      "label": "Phone",
      "hardware": {
        "...": "..."
      },
      "lists": {
        "chat": [
          "..."
        ],
        "coding": [
          "..."
        ]
      }
    }
  ]
}

New and popular

GET/v1/highlights

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The most recently released models mixed one-for-one with the most downloaded (last 30 days).

Returns

downloads_window_days and items: kind (new or popular), id, name, vendor_name, params_b, released_at, downloads, support, formats, smallest_gb, largest_gb, ready_download, ollama.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/highlights" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/highlights",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/highlights', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "downloads_window_days": 30,
  "items": [
    {
      "kind": "new",
      "id": "mellum2.1-12b-a2.5b-thinking",
      "name": "Mellum2.1-12B-A2.5B-Thinking",
      "vendor_name": "JetBrains",
      "params_b": 12.15,
      "released_at": "2026-09-20T10:52:55.000Z",
      "downloads": 803,
      "support": {
        "id": "current",
        "label": "Current",
        "limited": false
      },
      "formats": 7,
      "smallest_gb": 4.1,
      "largest_gb": 12.93,
      "ready_download": true,
      "ollama": null
    }
  ]
}

Hardware lookups

Find a GPU

GET/v1/hardware/gpus

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Graphics cards with kind and VRAM. Search for an autocomplete, or resolve a browser's WebGL renderer string to one card. Matching uses the longest name pattern contained in what you send.

Query parameters

qstring

Words that must all appear in the name. Up to 20 results.

rendererstring

A renderer string, for example ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11). Returns {match}.

Returns

Without parameters, every card. gpus (or match): id, name, gpu_vendor, kind (discrete, integrated, apple, unified), vram_gb, match.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/hardware/gpus?q=rtx%204070" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/hardware/gpus?q=rtx%204070",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/hardware/gpus?q=rtx%204070', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "gpus": [
    {
      "id": "nvidia-rtx-4070",
      "name": "NVIDIA GeForce RTX 4070",
      "gpu_vendor": "nvidia",
      "kind": "discrete",
      "vram_gb": 12,
      "match": [
        "rtx 4070"
      ]
    }
  ]
}

Find a phone or board

GET/v1/hardware/devices

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Phones, tablets and single-board computers with chip, RAM options and memory bandwidth. Send a name or model code as hardware.device_model and the API fills the rest. iOS identifiers such as iPhone17,1 do not match; send the marketing name or the chip.

Query parameters

qstring

Words in the name or chip. Up to 10 results.

modelstring

A name or model code. Returns {match}.

rendererstring

A board's GPU renderer. Returns {match}.

Returns

devices (or match): id, name, kind (phone, tablet, board), platform, soc, ram_options_gb, bandwidth_gbps, cpu_cores, speed_class.

Errors

`400 invalid_request`	Unknown filter.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/hardware/devices?model=SM-S928B" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/hardware/devices?model=SM-S928B",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/hardware/devices?model=SM-S928B', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "match": {
    "id": "galaxy-s24-ultra",
    "name": "Samsung Galaxy S24 Ultra",
    "kind": "phone",
    "platform": "android",
    "soc": "Snapdragon 8 Gen 3 for Galaxy",
    "ram_options_gb": [
      12
    ],
    "bandwidth_gbps": 76.8,
    "cpu_cores": 8,
    "speed_class": "flagship"
  }
}

Find a chip

GET/v1/hardware/chips

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

Phone and board chips with memory type and bandwidth, for devices not in the device list.

Query parameters

qstring

Words in the name. Up to 10 results.

namestring

A chip name. Returns {match}.

Returns

chips (or match): id, name, memory_type, bandwidth_gbps, cpu_cores.

Errors

`400 invalid_request`	Unknown filter.
`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/hardware/chips?name=Apple%20A18%20Pro" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/hardware/chips?name=Apple%20A18%20Pro",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/hardware/chips?name=Apple%20A18%20Pro', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "match": {
    "id": "apple-a18-pro",
    "name": "Apple A18 Pro",
    "memory_type": "LPDDR5X-7500",
    "bandwidth_gbps": 60,
    "cpu_cores": 6
  }
}

List hardware classes

GET/v1/hardware/tiers

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The four hardware classes. Send hardware.tier for a quick answer when the machine is unknown; the class is also what votes and min_tier use.

Returns

An array: id, label, description, preset (what tier fills in) and minimums (what a machine needs to be in the class).

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/hardware/tiers" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/hardware/tiers",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/hardware/tiers', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

[
  {
    "id": "mid",
    "label": "Mid",
    "description": "A dedicated graphics card with at least 4 GB",
    "preset": {
      "cpu_cores": 6,
      "ram_gb": 16,
      "vram_gb": 4
    },
    "minimums": {
      "cpu_cores": 4,
      "ram_gb": 8,
      "vram_gb": 4,
      "unified_gb": 16
    }
  }
]

Community

Get votes for a model

GET/v1/models/{id}/votes

Authentication: None; a session token adds your own vote.

Good and not-good votes from QuantTrail accounts, per hardware class. Never says who voted. With a session token the answer adds your own vote.

Path parameters

idstringRequired

Catalog model id.

Returns

model, total {up, down}, classes (tier, label, description, up, down), percent_after (the class size from which the website shows percentages) and yours ({tier, value, changeable_at} or null).

Errors

404 not_found No such model.

curl "https://quanttrailpicker.com/v1/models/qwen3-8b/votes" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/models/qwen3-8b/votes",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/models/qwen3-8b/votes', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "model": "qwen3-8b",
  "total": {
    "up": 3,
    "down": 1
  },
  "classes": [
    {
      "tier": "mid",
      "label": "Mid",
      "description": "A dedicated graphics card with at least 4 GB",
      "up": 2,
      "down": 0
    }
  ],
  "percent_after": 3,
  "yours": null
}

Vote on a model

POST/v1/models/{id}/votes

Authentication: Session token required (Authorization: Bearer <token>).

One vote per account per model, with the hardware class it was tried on. A vote can change 48 hours after it was cast or last changed; sending the same vote again is accepted.

Path parameters

idstringRequired

Catalog model id.

Body parameters

valuestringRequired

Whether it was a good fit.

One of up down.

tierstringRequired

Hardware class it ran on.

One of low mid high max.

Returns

The same shape as Get votes, with yours filled in.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`429 vote_locked`	Changed less than 48 hours ago; `message` gives the time.
`503 votes_disabled`	Voting is switched off.

curl -X POST "https://quanttrailpicker.com/v1/models/qwen3-8b/votes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION" \
  -d '{
  "value": "up",
  "tier": "mid"
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/models/qwen3-8b/votes",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    json={
        "value": "up",
        "tier": "mid",
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/models/qwen3-8b/votes', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
  body: JSON.stringify({
    "value": "up",
    "tier": "mid"
  }),
});
const data = await res.json();

Response

{
  "model": "qwen3-8b",
  "total": {
    "up": 4,
    "down": 1
  },
  "classes": [
    "..."
  ],
  "percent_after": 3,
  "yours": {
    "tier": "mid",
    "value": "up",
    "changeable_at": "2026-10-13T18:00:00.000Z"
  }
}

Phone and board survey

GET/v1/survey

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The most recommended models per phone and board class, from the survey. No counts, names or RAM.

Returns

classes: one per class with its top models.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/survey" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/survey",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/survey', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "classes": []
}

Account

List levels

GET/v1/plans

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The account levels with their limits. Read this instead of hard-coding the numbers; the operator can change them.

Returns

plans: id, label, position, price_month_usd, price_year_usd, price_once_usd, keys_max, requests_per_week (null: no limit), requests_per_minute, families_max (null: every family), description; and payments.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/plans" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/plans",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/plans', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "plans": [
    {
      "id": "free",
      "label": "Free",
      "position": 0,
      "price_month_usd": 0,
      "price_year_usd": null,
      "price_once_usd": null,
      "keys_max": 1,
      "requests_per_week": 1000,
      "requests_per_minute": 10,
      "families_max": 1,
      "description": "One API key for one model family, saved computers and votes."
    }
  ],
  "payments": "Paid levels are not on sale yet."
}

Get your account

GET/v1/me

Authentication: Session token required (Authorization: Bearer <token>).

Your level, this week's use across all keys, and your keys.

Returns

email, level (a plan with billing and expires_at), is_admin, week {starts, used, limit}, keys, family_change_days, plans. Each key: id, name, hint, status (active or revoked), families (null: every family), limits (null: none; see key limits), requests_this_week, last_used_at, created_at, rolled_at, families_changeable_at.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.

curl "https://quanttrailpicker.com/v1/me" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/me",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me', {
  headers: {'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
});
const data = await res.json();

Response

{
  "email": "you@example.com",
  "level": {
    "id": "free",
    "label": "Free",
    "keys_max": 1,
    "requests_per_week": 1000,
    "requests_per_minute": 10,
    "families_max": 1,
    "billing": null,
    "expires_at": null
  },
  "is_admin": false,
  "week": {
    "starts": "2026-10-05",
    "used": 126,
    "limit": 1000
  },
  "keys": [
    {
      "id": "u3f9a0c12b4d5",
      "name": "My app",
      "hint": "qt_u3f9a0c12b4d5_0f3c...b7c1",
      "status": "active",
      "families": [
        "qwen"
      ],
      "limits": {
        "quants": [
          "Q4_K_M"
        ]
      },
      "requests_this_week": 126,
      "last_used_at": "2026-10-11T21:04:11.000Z",
      "created_at": "2026-10-11T20:00:00.000Z",
      "rolled_at": "2026-10-11T20:00:00.000Z",
      "families_changeable_at": "2026-10-18T20:00:00.000Z"
    }
  ],
  "family_change_days": 7,
  "plans": [
    "..."
  ]
}

Create a key

POST/v1/me/keys

Authentication: Session token required (Authorization: Bearer <token>).

Makes an API key. The key is in the answer once; copy it then. The API page does the same with a form.

Body parameters

namestringRequired

A name for you, up to 60 characters.

familiesarray of strings

Family ids the key is for, up to the level's families_max. Required on levels with a family limit; optional elsewhere (empty: every family).

limitsobject

Limits on what the key can see, on any level: vendors, origins, tasks (a model must support at least one), support_levels, quants (lists of ids), family_kind ("brand" or "specialized"), license: "permissive" and allow_gated: false. Empty lists and "any" mean no limit there. null clears every limit. See key limits.

Returns

key (the only time it is shown), note, and the account summary from Get your account.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`400 invalid_request`	Name or families missing, unknown or too many.
`409 key_limit`	The level's key count is reached; revoke one first.

curl -X POST "https://quanttrailpicker.com/v1/me/keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION" \
  -d '{
  "name": "My app",
  "families": [
    "qwen"
  ],
  "limits": {
    "quants": [
      "Q4_K_M",
      "Q6_K"
    ],
    "license": "permissive"
  }
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/me/keys",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    json={
        "name": "My app",
        "families": ["qwen"],
        "limits": {
            "quants": ["Q4_K_M", "Q6_K"],
            "license": "permissive",
        },
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/keys', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
  body: JSON.stringify({
    "name": "My app",
    "families": [
      "qwen"
    ],
    "limits": {
      "quants": [
        "Q4_K_M",
        "Q6_K"
      ],
      "license": "permissive"
    }
  }),
});
const data = await res.json();

Response

{
  "key": "qt_u3f9a0c12b4d5_0f3c5d0e8a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "note": "Copy this key now. It is shown only this once.",
  "level": "...",
  "week": "...",
  "keys": [
    "..."
  ]
}

Update a key

POST/v1/me/keys/{id}

Authentication: Session token required (Authorization: Bearer <token>).

Renames a key, or changes its model families or limits. On levels with a family limit, families can change once every 7 days per key; everything else changes at once.

Path parameters

idstringRequired

The key id, for example u3f9a0c12b4d5.

Body parameters

namestring

New name.

familiesarray of strings

New family ids; empty for every family on a level without a family limit.

limitsobject

Returns

The account summary.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`404 not_found`	Not one of your keys.
`429 families_locked`	Families changed less than 7 days ago.

curl -X POST "https://quanttrailpicker.com/v1/me/keys/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION" \
  -d '{
  "name": "Production server",
  "limits": {
    "tasks": [
      "coding"
    ],
    "allow_gated": false
  }
}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/me/keys/{id}",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    json={
        "name": "Production server",
        "limits": {
            "tasks": ["coding"],
            "allow_gated": False,
        },
    },
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/keys/{id}', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
  body: JSON.stringify({
    "name": "Production server",
    "limits": {
      "tasks": [
        "coding"
      ],
      "allow_gated": false
    }
  }),
});
const data = await res.json();

Response

{
  "level": "...",
  "week": "...",
  "keys": [
    "..."
  ]
}

Roll a key

POST/v1/me/keys/{id}/roll

Authentication: Session token required (Authorization: Bearer <token>).

Replaces the secret. The old key stops working at once. Rolling a revoked key makes it active again if the level allows another active key.

Path parameters

idstringRequired

The key id.

Returns

key (shown once), note and the account summary.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`404 not_found`	Not one of your keys.
`409 key_limit`	No free key slot for a revoked key.

curl -X POST "https://quanttrailpicker.com/v1/me/keys/{id}/roll" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION" \
  -d '{}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/me/keys/{id}/roll",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    json={},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/keys/{id}/roll', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
  body: JSON.stringify({}),
});
const data = await res.json();

Response

{
  "key": "qt_u3f9a0c12b4d5_9a8b...",
  "note": "Copy this key now. It is shown only this once. The old key no longer works.",
  "keys": [
    "..."
  ]
}

Revoke a key

POST/v1/me/keys/{id}/revoke

Authentication: Session token required (Authorization: Bearer <token>).

Turns a key off. It stays in your list as revoked and frees a key slot.

Path parameters

idstringRequired

The key id.

Returns

The account summary.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`404 not_found`	Not one of your keys.

curl -X POST "https://quanttrailpicker.com/v1/me/keys/{id}/revoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION" \
  -d '{}'

import os
import requests

r = requests.post(
    "https://quanttrailpicker.com/v1/me/keys/{id}/revoke",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    json={},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/keys/{id}/revoke', {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
  body: JSON.stringify({}),
});
const data = await res.json();

Response

{
  "keys": [
    {
      "id": "u3f9a0c12b4d5",
      "status": "revoked",
      "...": "..."
    }
  ]
}

Saved computers

GET/v1/me/presets

Authentication: Session token required (Authorization: Bearer <token>).

Computers the account chose to save, up to 10. QuantTrail re-checks them as new models arrive and flags when a better one fits.

POST /v1/me/presets saves one: name, hardware, task (default chat), context_tokens, preferences (priority, min_speed, quants only). 409 preset_limit at 10.
GET or POST /v1/me/presets/{id} reads or changes one.
POST /v1/me/presets/{id}/check re-checks it now; POST /v1/me/presets/{id}/remove removes it.
POST /v1/me/presets/refresh re-checks every computer not checked for a day.

Returns

presets and limit. Each: id, name, hardware, task, context_tokens, preferences, best and largest (top three by score and by size: id, name, quant, score, params_b, file_gb, released_at, download, fit, speed), previous_best, checked_at, better_since, created_at.

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.
`409 preset_limit`	Ten computers saved already.

curl "https://quanttrailpicker.com/v1/me/presets" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/me/presets",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/presets', {
  headers: {'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
});
const data = await res.json();

Response

{
  "presets": [
    {
      "id": "6b1d6c0e-0d5f-4a8e-9a3b-2f1c4e5d6a7b",
      "name": "Desk PC",
      "hardware": {
        "platform": "windows",
        "ram_gb": 32,
        "gpu": "nvidia",
        "vram_gb": 12
      },
      "task": "coding",
      "context_tokens": 16384,
      "preferences": {},
      "best": [
        "..."
      ],
      "largest": [
        "..."
      ],
      "previous_best": [],
      "checked_at": "2026-10-11T08:00:00.000Z",
      "better_since": null,
      "created_at": "2026-10-10T19:00:00.000Z"
    }
  ],
  "limit": 10
}

Followed families

GET/v1/me/watches

Authentication: Session token required (Authorization: Bearer <token>).

Model families the account follows, and the models new in them since it last looked.

POST /v1/me/watches with {"family": "qwen"} follows a family.
POST /v1/me/watches/seen marks everything as seen.
POST /v1/me/watches/{family}/remove stops following.

Returns

watches (family, label, since, seen_at) and new (id, name, family, vendor_name, params_b, released_at, first_seen_at, links).

Errors

`401 sign_in_required`	No valid session token, or the email is not confirmed.
`503 sign_in_unavailable`	The sign-in service did not answer. Retry later.

curl "https://quanttrailpicker.com/v1/me/watches" \
  -H "Authorization: Bearer $QUANTTRAIL_SESSION"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/me/watches",
    headers={"Authorization": "Bearer " + os.environ["QUANTTRAIL_SESSION"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/me/watches', {
  headers: {'Authorization': `Bearer ${process.env.QUANTTRAIL_SESSION}`},
});
const data = await res.json();

Response

{
  "watches": [
    {
      "family": "qwen",
      "label": "Qwen",
      "since": "2026-10-11T20:00:00.000Z",
      "seen_at": "2026-10-11T20:00:00.000Z"
    }
  ],
  "new": []
}

Service

Site settings

GET/v1/site

Authentication: Optional API key. Anonymous calls work within the anonymous limits.
Counts toward: Your key's minute and weekly limits when a key is sent. Not limited without one.

The donation message, donation links and contact address shown on the website.

Returns

donation_message, donations, contact_email.

Errors

`401 invalid_key`	The key is malformed, rolled or revoked.
`429 rate_limited`	Per-minute key limit, or an anonymous timeout. Wait `Retry-After` seconds.
`429 weekly_limit`	The account used its weekly requests.

curl "https://quanttrailpicker.com/v1/site" \
  -H "X-QuantTrail-Key: $QUANTTRAIL_API_KEY"

import os
import requests

r = requests.get(
    "https://quanttrailpicker.com/v1/site",
    headers={"X-QuantTrail-Key": os.environ["QUANTTRAIL_API_KEY"]},
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/v1/site', {
  headers: {'X-QuantTrail-Key': process.env.QUANTTRAIL_API_KEY},
});
const data = await res.json();

Response

{
  "donation_message": "Donations are appreciated and keep the server running.",
  "donations": [],
  "contact_email": null
}

Health check

GET/health

Authentication: None.

Whether the service is up. Not counted, not limited.

Returns

ok, service, version.

curl "https://quanttrailpicker.com/health"

import requests

r = requests.get(
    "https://quanttrailpicker.com/health",
    timeout=20,
)
r.raise_for_status()
print(r.json())

const res = await fetch('https://quanttrailpicker.com/health', {
});
const data = await res.json();

Response

{
  "ok": true,
  "service": "QuantTrail",
  "version": "0.2.0"
}