Ollama /api/show: check model metadata before loading

tutorialworkflowtroubleshooting

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_length from a Modelfile num_ctx override.
  • Catch missing capabilities such as tools, vision, or thinking before a client request fails.

Honest take: Check /api/show before 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.

EndpointRequest methodLoads model into VRAM?Primary fields returnedQuestion it answers
/api/tagsGETNomodels[].name, size, digest, detailsWhich model tags are installed on disk?
/api/showPOSTNodetails, model_info, parameters, capabilities, templateWhat does one installed tag support and configure?
/api/psGETNomodels[].name, size, size_vram, context_length, expires_atWhich 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:

  1. details: Reports family, families, parameter_size, quantization_level, and format. A tag named :latest or a custom alias can hide whether the underlying weights use Q4_0, Q4_K_M, Q8_0, or F16. Checking quantization_level and parameter_size first prevents accidentally loading a heavier quantization than your GPU budget allows.
  2. capabilities: Lists supported modes such as "completion", "vision", "tools", "thinking", or "embedding". Sending images to a tag that only advertises ["completion"], or sending tools definitions to a tag without "tools", causes avoidable request errors or ignored inputs.
  3. model_info: Exposes GGUF header metadata keyed by architecture. Look at general.architecture (for example, "llama") and then read <architecture>.context_length (such as llama.context_length). That integer is the maximum context length declared by the model metadata.
  4. parameters: Contains a newline-delimited string of Modelfile PARAMETER directives baked into the tag, such as num_ctx, num_keep, temperature, or stop. As documented in the Modelfile reference and context-length guide, a PARAMETER num_ctx line in the Modelfile overrides the default runtime context window unless your request overrides it again in options.

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_ctx wins within parameters: If a Modelfile contains multiple num_ctx lines, 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 hardcoding llama.context_length, the script resolves general.architecture (falling back to details.family) and looks up <architecture>.context_length dynamically.
  • Explicit status classification: It separates MISSING_CAPABILITY, CONTEXT_EXCEEDS_MODEL, PARAMETER_OVERRIDE_ACTIVE, and READY_TO_TEST so 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 caseInput conditionObserved statusWhy this matters before loading
Matching capability and contextRequire "vision", request 4096 tokens on an 8192-limit fixtureREADY_TO_TESTConfirms the tag declares vision support and fits the target context ceiling
Unsupported capabilityRequire "tools" when capabilities is ["completion", "vision"]MISSING_CAPABILITYStops a tool-calling workflow before loading a non-tool model into VRAM
Excessive context requestRequest 16384 tokens when llama.context_length is 8192CONTEXT_EXCEEDS_MODELCatches a context setting above the model’s declared architectural limit
Baked-in Modelfile num_ctxparameters includes num_ctx 4096 while architecture allows 8192PARAMETER_OVERRIDE_ACTIVEReveals that the tag enforces a 4,096-token default unless overridden
Error or malformed payloadServer error object, missing architecture, or non-integer num_ctxRaises ValueErrorPrevents 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:

  1. Read parameter_size and quantization_level from /api/show: Confirm whether an alias points to an 8.0B Q4_0 build or a much larger checkpoint.
  2. Check configured_num_ctx and your request’s options.num_ctx: Increasing num_ctx from 4096 to 32768 multiplies KV cache memory requirements by 8 for the same model and batch settings, even when the weights on disk never change.
  3. 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

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?

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.