# List models

> List every model your key can use right now, priced in the key's billing currency.

`GET https://api.numes.ai/api/v1/models`

Source: https://0.0.0.0:3000/docs/api-reference/models/list-models
Authorization: Bearer inference key

Lists only models with at least one available endpoint priced in your key's currency. Each row describes one representative endpoint; use [List model endpoints](/docs/api-reference/models/list-model-endpoints) to compare every endpoint that serves a model. `context_length` bounds prompt plus output; the optional `max_input_tokens` is a separate input limit. Without `sort`, models are ordered by ID. Filter with comma-separated `output_modalities` and `supported_parameters`. See [Models](/docs/models) for the full field guide.

```request
{
  "method": "GET",
  "path": "/models",
  "query": { "output_modalities": "text", "sort": "pricing-low-to-high" }
}
```

```json title="Response 200"
{
  "data": [
    {
      "id": "openai/gpt-6-luna",
      "canonical_slug": "openai/gpt-6-luna",
      "name": "Example Model",
      "description": "A compact general-purpose model.",
      "created": 1790000000,
      "context_length": 1047576,
      "billing_currency": "USD",
      "architecture": {
        "modality": "text+image->text",
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"],
        "tokenizer": "GPT"
      },
      "pricing": {
        "prompt": "0.0000001",
        "completion": "0.0000004",
        "request": "0",
        "image": "0",
        "audio": "0",
        "input_cache_read": "0.000000025"
      },
      "supported_parameters": ["max_tokens", "temperature", "top_p", "stop", "seed", "tools", "tool_choice", "response_format"],
      "maximum_output_length": 32768,
      "embeddings": false,
      "top_provider": { "context_length": 1047576, "max_completion_tokens": 32768 }
    }
  ]
}
```

## Headers

- `X-Request-Id` (string; Length 1–128): Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

## Query parameters

- `output_modalities` (string)
- `supported_parameters` (string)
- `sort` (enum<string>; one of pricing-low-to-high, pricing-high-to-low, context-high-to-low, newest)

## Response 200 (application/json)

- `data` (array<object>; required)
  - `billing_currency` (enum<string>; one of USD, BTC)
  - `usage_meter` (string): Gateway billing-unit algorithm; not the native tokenizer used for context limits.
  - `id` (string; required; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$)
  - `canonical_slug` (string; required; Pattern ^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$)
  - `name` (string; required)
  - `description` (string)
  - `created` (integer<int64>; required)
  - `context_length` (integer; required)
  - `architecture` (object; required)
    - `modality` (string; required)
    - `input_modalities` (array<enum<string>>; required; one of text, image, file, audio)
    - `output_modalities` (array<enum<string>>; required; one of text, image, audio, embeddings)
    - `tokenizer` (string; required)
    - `instruct_type` (string | null)
  - `pricing` (object; required): Exact per-unit prices in the inference key's immutable billing currency. For BTC keys, values are Bitcoin base units (1 is one satoshi), token prices have up to thirty decimal places, and clients may display them with BIP177 notation such as ₿123/M.

    - `pricing_basis` (enum<string>; one of fixed, usd_indexed)
    - `reference` (object)
      - `id` (string<uuid>; required)
      - `policy` (string; required)
      - `usd_per_btc` (string; required)
      - `observed_at` (string<date-time>; required)
      - `expires_at` (string<date-time>; required)
    - `usd_rates` (map<string, string>): USD anchor rates for the same displayed price categories; present only for USD-indexed Bitcoin schedules.
    - `input_cache_read` (string; Pattern ^[0-9]+(\.[0-9]+)?$)
    - `input_cache_write` (string; Pattern ^[0-9]+(\.[0-9]+)?$)
    - `prompt` (string; required; Pattern ^-?[0-9]+(\.[0-9]+)?$)
    - `completion` (string; required; Pattern ^-?[0-9]+(\.[0-9]+)?$)
    - `request` (string; required; Pattern ^-?[0-9]+(\.[0-9]+)?$)
    - `image` (string; required; Pattern ^-?[0-9]+(\.[0-9]+)?$)
    - `audio` (string; required; Pattern ^-?[0-9]+(\.[0-9]+)?$)
  - `supported_parameters` (array<string>; required)
  - `max_input_tokens` (integer; Range ≥ 1): Independent token input ceiling of the representative offer, when declared. This is separate from the combined context window.
  - `maximum_output_length` (integer | null; Range ≥ 1)
  - `embeddings` (boolean; default false)
  - `supported_hosted_tools` (array<enum<string>>; one of openrouter.web_search@1, openrouter.web_fetch@1, openrouter.datetime@1, openrouter.image_generation@1, openrouter.apply_patch@1, openrouter.fusion@1, openrouter.advisor@1, openrouter.subagent@1, openai.web_search@1, openai.file_search@1, openai.code_interpreter@1, openai.image_generation@1, openai.shell@1, openai.mcp@1, openai.connectors@1, openai.tool_search@1, openai.skills@1, anthropic.web_search@1, anthropic.web_fetch@1, anthropic.code_execution@1, anthropic.advisor@1, anthropic.tool_search@1, anthropic.mcp@1, google.search@1, google.maps@1, google.url_context@1, google.file_search@1, google.code_execution@1)
  - `reasoning` (object)
    - `default_effort` (string | null)
    - `default_enabled` (boolean)
    - `mandatory` (boolean)
    - `supports_max_tokens` (boolean)
    - `supported_efforts` (array<enum<string>>; one of none, minimal, low, medium, high, xhigh, max)
  - `top_provider` (object)
    - `context_length` (integer; required)
    - `max_completion_tokens` (integer | null; required; Range ≥ 1)
    - `is_moderated` (boolean)
  - `access` (object): Numes extension present only on a shared model: an access-restricted variant whose `id` is the canonical slug plus `:org-<handle>`, usable only by members of that organization (docs/MODEL_SHARING.md).
    - `kind` (enum<string>; required; one of organization)
    - `organization` (object; required)
      - `handle` (string; required; Pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])$)
      - `display_name` (string; required)

## Response default (application/json)

- `error` (object; required)
  - `code` (integer; required)
  - `message` (string; required)
  - `metadata` (object)
- `openrouter_metadata` (object)