Get Model

The /v1/models/{model_id} endpoint retrieves detailed configuration and operational metadata for a single model or smart router alias by its unique identifier. Use this endpoint to verify model availability, inspect provider ownership, and confirm tenant access entitlements before issuing high-volume inference batches.

GET https://api.nrouter.ai/v1/models/{model_id}

Architectural Role & Lifecycle

When an application queries /v1/models/{model_id}, nRouter executes a rapid validation sequence:

1. Phase 1: In-Memory Key Auth & Model ACL: Hashes the virtual key (sk-nrouter-...) and checks if the model exists in nRouter's global catalog and whether the caller's organization has permissions to access it.
2. Dynamic Resolution: If the requested identifier is a concrete model (e.g. gpt-5.5, claude-sonnet-4-5-20250929), the endpoint returns the model's provider specifications. If it is a virtual smart router alias (e.g. nrouter/auto), it returns the alias routing configuration.
3. Tenant Security Isolation: If a model exists globally but has been restricted or disabled for your organization, the gateway returns HTTP 404 Not Found (model_not_found) to prevent topology enumeration.
4. Immediate Response: The response is served in single-digit milliseconds with $0 in billing charges.

Path Parameters

Request & Response Headers

Inbound Request Headers

Outbound Response Headers

Response Payload

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1709251200,
  "owned_by": "openai"
}

Field Breakdown

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const model = await client.models.retrieve("gpt-5.5");
console.log(`Model: ${model.id}`);
console.log(`Owned By: ${model.owned_by}`);

Error Handling & Status Codes

{
  "error": {
    "type": "gateway_error",
    "message": "The model 'non-existent-model' does not exist or you do not have access to it.",
    "code": "model_not_found"
  }
}

Model Metadata Architecture & Dynamic Access Control

The model detail endpoint (GET /v1/models/{model_id}) resolves real-time telemetry, access permissions, context boundaries, and pricing structures directly from the gateway's authoritative database.

Tenant Model ACL Validation

Every request to retrieve model metadata verifies multi-tiered access control lists:

1. Organization-Level Entitlements: Organizations on Enterprise plans can configure custom model allowlists and denylists. If a model is restricted by your organization administrator, the endpoint returns HTTP 404 with model_not_found to prevent information leaks.
2. Virtual Key Restrictions: Virtual keys can be scoped to specific model families (e.g. gpt-5.5 only). If a key attempts to query an unauthorized model, the gateway enforces key-level isolation.
3. Provider Region & Compliance Rules: If your organization enforces strict data sovereignty policies (e.g. EU-only processing), models hosted exclusively in disallowed regions are automatically omitted from resolution.

Context Limits & Pricing Fields

The JSON response includes machine-readable metadata essential for client-side token budgeting:

• context_length: Maximum supported token context window (e.g. 128000, 200000, 1000000).
• pricing.prompt: Cost in USD per input token at the exact provider list price ($0 markup).
• pricing.completion: Cost in USD per generated completion token.
• pricing.image: Flat USD rate per generated image or image input tile.
• pricing.request: Flat invocation charge if applicable.

Dynamic Fallback Chains & Alias Resolution

When querying model metadata, nRouter supports both canonical model identifiers (e.g. anthropic/claude-3-5-sonnet) and virtual aliases (e.g. nrouter/auto or custom organization aliases).

• Canonical Model IDs: Resolves to the specific foundation model deployment across configured provider regions.
• Smart Router Targets: For managed aliases like nrouter/auto, nRouter looks at the request (whether it asks for reasoning, how long the input and requested output are, whether it uses tools over many turns) and at the kind of task, then picks a model from a pool that nRouter manages; if that model is unavailable it falls back to another model that costs the same or less. Inspecting the router alias does not reveal fallback chains or candidate models; the response always reports nrouter/auto as the model and is billed at the list price of the model that answered.
• Zero-Markup Transparency: Every pricing entry matches upstream cloud provider rates exactly, enabling high-fidelity FinOps forecasting and auditing across multi-tenant deployments.
• Cache Header Guarantees: Model configuration payloads carry HTTP ETag and Cache-Control headers, allowing client applications to cache definitions for up to 60 seconds with background revalidation.

curl -X GET "https://example.com/v1/models/string"

{  "id": "gpt-4o",  "object": "model",  "owned_by": "nrouter"}