> This page is for version 1.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/metadata-api/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/metadata-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/metadata-api/_mcp/server.

# Core Concepts Overview for NIM Metadata API

> Understand profiles, GPU targeting, and the serialization rules that determine how to interpret a NIM Metadata API response.

To interpret a response from the NIM Metadata API correctly, you first need to
understand profiles, how the API expresses GPU targeting, and the serialization
rules that govern which fields appear at all. For the endpoint and field
listings, refer to the
[Reference Overview](/nim/metadata-api/reference/reference-overview).

## Profiles

A profile is a deployable configuration of a NIM microservice. Each profile
pairs the model with a GPU target, a numeric precision, an inference backend,
and a parallelism layout. A single NIM microservice can publish a handful of
profiles or several hundred.

Profiles are the section of the response you use most. The profile you select
determines the hardware you need, so comparing profiles is the primary reason
to call this API. Every profile carries a `profile_id`, which is the value you
supply at deployment time.

Treat `profile_id` as an opaque identifier. Compare it for equality, and never
parse it or derive meaning from its structure. Identifiers generated by
different versions of the publishing toolchain were computed differently, so the
internal structure is not stable across publication vintages.

### Hardware Fit

The primary hardware-fit field is `min_vram_per_device_gb`, which states the
minimum vRAM required per GPU rather than a total across GPUs. A profile with
`tensor_parallel_size` set to 4 and `min_vram_per_device_gb` set to 80.0
requires four GPUs with 80 GB each, not 80 GB in aggregate.

The number of GPUs a profile requires is the product of its tensor parallel size
and its pipeline parallel size, treating an absent value as 1:

```text
required_gpus = (tensor_parallel_size or 1) × (pipeline_parallel_size or 1)
```

## GPU Targeting

Not every profile targets a specific GPU. Many NIM microservices ship profiles
that run anywhere with sufficient vRAM. Those profiles omit `gpu` and
`gpu_device` entirely, and can carry an empty `tested_gpu_devices` array.

An empty or absent GPU field is not a broken response. It means the profile is
not tied to a particular GPU. Read it as "no GPU restriction recorded" rather
than "no GPUs supported."

The API preserves this distinction precisely, as described in the following
table:

| What You See                                  | What It Means                                                              |
| --------------------------------------------- | -------------------------------------------------------------------------- |
| `gpu_device` present                          | This profile targets that specific GPU.                                    |
| `tested_gpu_devices` with one or more entries | Validated on these specific devices.                                       |
| `tested_gpu_devices` present and empty        | No validation information recorded. GPUs were not tested with the profile. |
| `tested_gpu_devices` absent                   | No testing information recorded.                                           |

### Comparing gpu and gpu_device

Both fields describe the target GPU, but they are not interchangeable:

* `gpu_device` is a PCI identifier in the form `pciDeviceId:pciVendorId`,
  such as `2330:10de`. It is precise and machine-comparable, so match on this
  field.
* `gpu` is a human-readable name such as `H100` or `A100_1x`. Formats vary
  between NIM microservices, so it is not a reliable join key. Display it, but
  do not match on it.

When both fields are present, they describe the same GPU. When only `gpu` is
present, you can show it to a reader but you cannot reliably match it
programmatically, so treat that profile as unverified rather than assuming a
match.

## Absent Means Unknown

The service serializes responses with non-null inclusion, which means it never
emits `null`. If a field has no value, the key is absent entirely. A response
contains what was supplied at publish time and nothing else, so two profiles in
the same response body can carry different sets of keys.

The consequence matters for every decision you make from this data. An absent
field records the absence of information, not a negative value. A missing
`feat_lora` does not mean LoRA adapters are unsupported; it means nothing was
recorded. Never treat an absent boolean as false, or an absent number as zero.

There is one deliberate exception to the omission rule. An explicitly empty
`tested_gpu_devices` array is preserved, so "tested on nothing" stays
distinguishable from "unknown."

For the complete set of serialization rules, refer to
[Response Fields](/nim/metadata-api/reference/response-fields).

## Schema Evolution

The set of fields grows as the schema evolves, so a response can contain keys
that postdate your integration. Parse permissively, ignore keys you do not
recognize, and never fail on an unrecognized key.

Treat `precision` and `inference_backend` as open strings rather than
enumerations. New values appear without notice, so carry an unrecognized value
through instead of rejecting it. For the full set of rules that keep an
integration working across schema changes, refer to
[Notes for Automated Agents](/nim/metadata-api/guides/automated-agents).