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

# Current Limitations of the NIM Metadata API

> The current constraints of the NIM Metadata API, including partial coverage, unstandardized throughput figures, and planned field-shape changes.

The following constraints apply to the NIM Metadata API today, so you can plan
around them. For the fields these constraints refer to, refer to
[Response Fields](/nim/metadata-api/reference/response-fields).

## Coverage

Coverage is partial and growing. Metadata is attached at publish time, so NIM
microservices released before this API launched in September 2026 generally lack
metadata until they are republished. Design for a 404 status code as a normal
outcome rather than an error.

## Planned Field-Shape Changes

The `gpu` and `gpu_device` fields can become arrays. A single profile can be
valid on several compatible GPUs, which the current single-string fields cannot
express.

To make that change a non-event for your integration, write your parser to
accept either a string or a list now. For the pattern, refer to rule 4 in
[Notes for Automated Agents](/nim/metadata-api/guides/automated-agents).

## Unstandardized and Optional Fields

The following table describes fields you should treat with care:

| Field            | Limitation                                                                                                                                        | Guidance                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `throughput`     | Units and measurement conditions are not yet fixed, so figures are not comparable across NIM microservices.                                       | Treat it as informational. Do not use it as a ranking key across NIM microservices.                                 |
| `workspace_hash` | Optional today.                                                                                                                                   | Do not assume its presence, but use it for integrity verification when it is present.                               |
| `profile_id`     | Semantics vary by publication vintage, because identifiers generated by different versions of the publishing toolchain were computed differently. | Treat it as an opaque identifier. Compare it for equality, and never parse it or derive meaning from its structure. |

## Caching

The API offers no ETag header, no Last-Modified header, and no
conditional-request support. Cache based on tag stability instead, as described
in [Notes for Automated Agents](/nim/metadata-api/guides/automated-agents).

## Best Practices

Apply the following practices to work within these constraints:

* **Treat a 404 status code as data, not failure.** It is a definitive answer
  about metadata availability.
* **Parse permissively.** Accept unrecognized keys and both shapes of the GPU
  fields.
* **Rank on fields with defined semantics.** Use `min_vram_per_device_gb` and
  parallelism sizes rather than `throughput` when comparing NIM
  microservices.
* **Verify entitlement separately.** An absent
  `allowed_deployment_regions` value means no recorded restriction, so confirm
  license terms rather than inferring them from absence.

## Related Topics

* [Response Fields](/nim/metadata-api/reference/response-fields)
* [Notes for Automated Agents](/nim/metadata-api/guides/automated-agents)
* [Troubleshooting](/nim/metadata-api/troubleshooting)