Ollama /api/show: check model metadata before loading
TL;DR: Query Ollama’s /api/show endpoint before sending a first prompt to an unfamiliar tag. That metadata response reveals the model’s architecture, quantization level, advertised capabilities, architectural context limit, and baked-in Modelfile num_ctx overrides without allocating VRAM or starting inference.
What you’ll be able to do:
- Inspect an installed Ollama tag’s metadata without loading weights into GPU memory.
- Separate a model’s architectural
context_lengthfrom a Modelfilenum_ctxoverride. - Catch missing capabilities such as
tools,vision, orthinkingbefore a client request fails.
Honest take: Check
/api/showbefore blaming your GPU or rewriting a client when a local model rejects tools, drops images, or runs with an unexpected context window.
Why should you inspect /api/show before loading a model?
Sending a chat or completion request to an unfamiliar tag forces Ollama to load the model into memory before you discover whether the tag matches your workload. If the tag is a different quantization than you expected, lacks vision or tool-calling support, or carries a custom num_ctx parameter in its Modelfile, that first request wastes load time and can evict a model that was already resident in VRAM.
Ollama’s official API specification, checked November 14, 2026, defines POST /api/show as a metadata endpoint that returns details, model_info, parameters, template, modelfile, and capabilities for an installed model name. Because it reads local manifest and GGUF metadata rather than starting a runner for generation, you can run a preflight check in milliseconds using only Python’s standard library.
This inspection requires no GPU, no model inference, no extra download, and no paid API. It verifies what an installed tag declares on disk. It does not measure tokens-per-second throughput or prove that a model’s answers will be accurate for your prompt.
How do /api/tags, /api/show, and /api/ps differ?
Local troubleshooting often mixes up three distinct inventory endpoints. Each endpoint answers a different question about your Ollama server. Compare the local tags reference, the /api/show section of the upstream API documentation, and the running models reference.
| Endpoint | Request method | Loads model into VRAM? | Primary fields returned | Question it answers |
|---|---|---|---|---|
/api/tags | GET | No | models[].name, size, digest, details | Which model tags are installed on disk? |
/api/show | POST | No | details, model_info, parameters, capabilities, template | What does one installed tag support and configure? |
/api/ps | GET | No | models[].name, size, size_vram, context_length, expires_at | Which models are currently loaded in memory right now? |
If a tag does not appear in /api/tags, /api/show returns a not-found error because the tag is not installed on that server. Refer to the wrong-server and missing-tag troubleshooting guide when a client points at the wrong host or tag string. If a model is already running and you need to compare disk size against active memory allocation, use the /api/ps memory reporting guide.
/api/show fills the gap between those two checks. Once you confirm a tag exists on disk, /api/show tells you whether that tag is suitable for your request before /api/ps ever shows a loaded runner.
What fields in /api/show prevent avoidable failures?
Four sections of the /api/show response catch most pre-load configuration mistakes:
details: Reportsfamily,families,parameter_size,quantization_level, andformat. A tag named:latestor a custom alias can hide whether the underlying weights useQ4_0,Q4_K_M,Q8_0, orF16. Checkingquantization_levelandparameter_sizefirst prevents accidentally loading a heavier quantization than your GPU budget allows.capabilities: Lists supported modes such as"completion","vision","tools","thinking", or"embedding". Sendingimagesto a tag that only advertises["completion"], or sendingtoolsdefinitions to a tag without"tools", causes avoidable request errors or ignored inputs.model_info: Exposes GGUF header metadata keyed by architecture. Look atgeneral.architecture(for example,"llama") and then read<architecture>.context_length(such asllama.context_length). That integer is the maximum context length declared by the model metadata.parameters: Contains a newline-delimited string of ModelfilePARAMETERdirectives baked into the tag, such asnum_ctx,num_keep,temperature, orstop. As documented in the Modelfile reference and context-length guide, aPARAMETER num_ctxline in the Modelfile overrides the default runtime context window unless your request overrides it again inoptions.
Capturing a response for inspection takes one command against your local server:
curl -sS http://localhost:11434/api/show \
-d '{"model":"YOUR_INSTALLED_MODEL"}' > show-response.json
Do not pass "verbose": true during a quick preflight check unless you specifically need tokenizer token arrays. The upstream API documentation notes that verbose=true populates large fields such as tokenizer.ggml.tokens, tokenizer.ggml.merges, and tokenizer.ggml.token_type, which add megabytes of output without changing the capability or context-limit fields.
How can you validate a saved /api/show payload in Python?
The helper below reads a saved /api/show JSON file, validates the structure, extracts the architecture and context limits, parses any num_ctx lines inside parameters, and checks an optional required capability or requested context window.
Save this script as inspect_show.py:
import json
import sys
def parse_num_ctx(parameters_text):
if not isinstance(parameters_text, str):
raise ValueError("parameters must be a string")
values = []
for raw_line in parameters_text.splitlines():
parts = raw_line.strip().split()
if len(parts) >= 2 and parts[0] == "num_ctx":
try:
value = int(parts[1])
except ValueError as exc:
raise ValueError("num_ctx must be an integer") from exc
if value <= 0:
raise ValueError("num_ctx must be positive")
values.append(value)
return values[-1] if values else None
def inspect_show(payload, required_capability=None, requested_ctx=None):
if not isinstance(payload, dict):
raise ValueError("show payload must be a JSON object")
if "error" in payload:
raise ValueError("server error: " + str(payload["error"]))
details = payload.get("details", {})
model_info = payload.get("model_info", {})
capabilities = payload.get("capabilities", [])
if not isinstance(details, dict) or not isinstance(model_info, dict):
raise ValueError("details and model_info must be objects")
if not isinstance(capabilities, list) or not all(
isinstance(item, str) for item in capabilities
):
raise ValueError("capabilities must be an array of strings")
arch = model_info.get("general.architecture") or details.get("family")
if not isinstance(arch, str) or not arch.strip():
raise ValueError("missing model architecture")
arch_ctx = model_info.get(f"{arch}.context_length")
if arch_ctx is not None and (
isinstance(arch_ctx, bool) or not isinstance(arch_ctx, int) or arch_ctx <= 0
):
raise ValueError("context_length must be a positive integer")
configured_ctx = parse_num_ctx(payload.get("parameters", ""))
effective_ctx = requested_ctx if requested_ctx is not None else configured_ctx
if required_capability and required_capability not in capabilities:
status = "MISSING_CAPABILITY"
elif (
arch_ctx is not None
and effective_ctx is not None
and effective_ctx > arch_ctx
):
status = "CONTEXT_EXCEEDS_MODEL"
elif (
configured_ctx is not None
and arch_ctx is not None
and configured_ctx != arch_ctx
):
status = "PARAMETER_OVERRIDE_ACTIVE"
else:
status = "READY_TO_TEST"
return {
"status": status,
"architecture": arch,
"quantization_level": details.get("quantization_level"),
"parameter_size": details.get("parameter_size"),
"arch_context_length": arch_ctx,
"configured_num_ctx": configured_ctx,
"capabilities": capabilities,
}
if __name__ == "__main__":
with open(sys.argv[1], encoding="utf-8") as handle:
data = json.load(handle)
cap = sys.argv[2] if len(sys.argv) > 2 and sys.argv[2] != "-" else None
req = int(sys.argv[3]) if len(sys.argv) > 3 else None
print(json.dumps(inspect_show(data, cap, req), ensure_ascii=False))
Run the script against a saved response file, passing - when you do not want to enforce a specific capability, or passing a capability name and a target num_ctx:
python3 inspect_show.py show-response.json vision 4096
The parser follows three deliberate rules:
- Last
num_ctxwins withinparameters: If a Modelfile contains multiplenum_ctxlines, reading all lines in order and keeping the last positive integer avoids silently stopping at an earlier line while still rejecting malformed non-integer values. - Architectural lookup uses
general.architecture: Rather than hardcodingllama.context_length, the script resolvesgeneral.architecture(falling back todetails.family) and looks up<architecture>.context_lengthdynamically. - Explicit status classification: It separates
MISSING_CAPABILITY,CONTEXT_EXCEEDS_MODEL,PARAMETER_OVERRIDE_ACTIVE, andREADY_TO_TESTso an automation script knows why a preflight stopped.
What did the local fixture tests verify?
We tested inspect_show.py on November 14, 2026 against a local JSON fixture modeled directly on the /api/show response structure in Ollama’s upstream docs/api.md (general.architecture: "llama", llama.context_length: 8192, quantization_level: "Q4_0", parameter_size: "8.0B", and capabilities: ["completion", "vision"]).
Running the helper against show-fixture.json with a required "vision" capability and a 4096 requested context produced:
{"status": "READY_TO_TEST", "architecture": "llama", "quantization_level": "Q4_0", "parameter_size": "8.0B", "arch_context_length": 8192, "configured_num_ctx": null, "capabilities": ["completion", "vision"]}
The test suite also verified four failure and override states using deterministic variations of that payload:
| Preflight test case | Input condition | Observed status | Why this matters before loading |
|---|---|---|---|
| Matching capability and context | Require "vision", request 4096 tokens on an 8192-limit fixture | READY_TO_TEST | Confirms the tag declares vision support and fits the target context ceiling |
| Unsupported capability | Require "tools" when capabilities is ["completion", "vision"] | MISSING_CAPABILITY | Stops a tool-calling workflow before loading a non-tool model into VRAM |
| Excessive context request | Request 16384 tokens when llama.context_length is 8192 | CONTEXT_EXCEEDS_MODEL | Catches a context setting above the model’s declared architectural limit |
Baked-in Modelfile num_ctx | parameters includes num_ctx 4096 while architecture allows 8192 | PARAMETER_OVERRIDE_ACTIVE | Reveals that the tag enforces a 4,096-token default unless overridden |
| Error or malformed payload | Server error object, missing architecture, or non-integer num_ctx | Raises ValueError | Prevents treating a failed /api/show lookup as a valid model check |
These results prove the parser’s control flow on saved /api/show JSON payloads. They are not live GPU benchmarks and do not claim that a specific model achieves a certain speed or quality at 4,096 or 8,192 tokens.
How does /api/show connect to VRAM planning and runtime behavior?
A passing /api/show check establishes what the model metadata declares, not whether your hardware has enough free memory to allocate the KV cache at that context length. Keep metadata verification and capacity planning as separate steps:
- Read
parameter_sizeandquantization_levelfrom/api/show: Confirm whether an alias points to an8.0BQ4_0build or a much larger checkpoint. - Check
configured_num_ctxand your request’soptions.num_ctx: Increasingnum_ctxfrom4096to32768multiplies KV cache memory requirements by8for the same model and batch settings, even when the weights on disk never change. - Estimate total memory before loading: Use the VRAM calculator to combine weight footprint and context overhead, and consult the 2026 GPU buying guide for local AI only after your actual workload outgrows your current hardware.
If /api/show confirms the tag supports "thinking" or "tools", keep the downstream response contracts straight as well. Thinking models emit reasoning separately from final text, as covered in our guide to separating thinking from content fields. Tool-calling endpoints differ between native and OpenAI-compatible routes, which you can verify with the tool-calls arguments diagnostic.
For self-hosted teams inspecting raw weight files before importing them into Ollama or llama.cpp, see the companion Safetensors header verification guide on AIFoss. If your local model powers an automated coding or review pipeline, pair this preflight with the Git diff exit-code review pipeline guide on AICoderScope.
Honest take: what can /api/show not tell you?
Do not treat READY_TO_TEST as proof that inference will succeed under load. /api/show does not check current free VRAM, concurrent requests waiting in the server queue, or whether a custom prompt template inside the Modelfile formats tool definitions properly for your task.
In addition, older or custom-imported GGUF models may omit certain metadata keys or rely on Ollama’s runtime defaults when parameters does not specify num_ctx. When configured_num_ctx is null, the effective context window comes from the server’s runtime configuration or the per-request options.num_ctx field, not from model_info’s maximum architectural ceiling.
Use /api/show for what it does best: a zero-VRAM gate that catches wrong tags, unexpected quantizations, missing capabilities, and hidden Modelfile num_ctx overrides before you load a single tensor.
Sources
- Upstream API reference (
POST /api/show,/api/tags,/api/ps) — Ollama GitHub - List local models (
GET /api/tags) — Ollama Docs - List running models (
GET /api/ps) — Ollama Docs - Modelfile reference (
PARAMETER num_ctx) — Ollama Docs - Context length configuration — Ollama Docs
Last updated November 14, 2026. Official Ollama documentation and upstream API references were checked on this date. Local verification used deterministic JSON fixtures with Python 3.13, without running model inference, hardware benchmarks, or paid API calls.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →Get the numbers before you buy
New GPU and mini-PC benchmarks, VRAM thresholds, and price checks — sent when there's something worth acting on, not on a schedule. No spam, unsubscribe anytime.