---
title: "List virtual model configs"
method: GET
path: "/ai-gateway/virtual-model-configs/list"
tags: ["ai-gateway"]
---

# List virtual model configs

`GET /ai-gateway/virtual-model-configs/list`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/ai-gateway/virtual-model-configs/list`
- Auth: HTTP bearer

List virtual model configs. For a team, returns all of its VMCs, or with `limit` or `cursor` one page ordered by `virtualModelSlug`. Across teams, pages newest-first. `includeArchived=false` omits archived VMCs.

## Query parameters

- `ownerId` string
- `limit` integer
- `cursor` string
- `includeArchived` 'true' | 'false'
- `teamId` string
- `slug` string

## Response `200`

- AiGatewayVirtualModelConfigList
  - `cursor` string, nullable, required: Cursor for the next page, or null when no more pages remain.
  - `virtualModelConfigs` AiGatewayVirtualModelConfig[], required: The page of VMCs.
    - `allowFallbackFromFast` false | true: Allow fallback from fast to standard providers on failure.
    - `baseUrl` string: For kind=relay: URL the gateway forwards requests to as a transparent proxy.
    - `byokCredentialIds` string[]: BYOK credential IDs allowed for this VMC.
    - `caching` 'auto': Use caching if available.
    - `createdAt` number, required: Creation timestamp (epoch ms).
    - `createdBy` string: User or app id that created this VMC.
    - `deleted` false | true, required: Whether this VMC is soft-deleted.
    - `description` string: Optional description for UI.
    - `disallowPromptTraining` false | true: Only use providers that will not train on your prompts.
    - `displayName` string: Human-readable name for UI.
    - `has` string[]: Limit providers to those with these features.
    - `hipaaCompliant` false | true: Only use HIPAA-compliant providers.
    - `inferenceRegion` object: Region pinned on the VMC for system-credential routing (alias/router only).
      - `geoRegion` string: Geo zone (e.g. "us", "eu").
      - `providerRegion` string: Provider-specific region identifier.
      - `providers` object: Per-provider region overrides keyed by provider slug.
      - `scope` 'global' | 'specific' | 'zone': Pin scope: `specific` (one provider region), `zone` (geo zone), or `global`.
    - `instanceId` string: The concrete model-provider instance this VMC resolves to.
    - `kind` string, required: VMC kind: alias, relay, or router.
    - `models` union[]: For kind=router: ordered candidates, bare slugs/references or `{ slug, ...attributes }`. For kind=alias: ordered fallback model slugs, optionally led by one conditional `{ model, when }` entry, used when the primary model's answers match `when`.
      - union
        - string
        - object: For kind=router: ordered candidates, bare slugs/references or `{ slug, ...attributes }`. For kind=alias: ordered fallback model slugs, optionally led by one conditional `{ model, when }` entry, used when the primary model's answers match `when`.
          - `intelligence` number: Highest task level the member handles, in [0, 1]. Read by the intelligence selector.
          - `slug` string, required
        - object: For kind=router: ordered candidates, bare slugs/references or `{ slug, ...attributes }`. For kind=alias: ordered fallback model slugs, optionally led by one conditional `{ model, when }` entry, used when the primary model's answers match `when`.
          - `model` string, required
          - `when` union, required
            - object: Without a question, checks every Choice and Score question.
              - …
            - object: Without a question, checks every Boolean question.
              - …
            - object
              - …
            - object
              - …
            - object
              - …
    - `modelSlug` string: Canonical model slug this VMC maps to (e.g. "creator/model"). Not used by kind=router.
    - `observabilityTags` string[]: Observability tags attached to requests through this VMC.
    - `ownerId` string, required: Team (owner) that owns this VMC.
    - `providerOnly` string[]: Restrict routing to only these providers.
    - `providerOptions` object: Arbitrary per-provider AI SDK options, keyed by gateway provider slug.
    - `providerOrder` string[]: Ordered list of providers to try as fallbacks on failure.
    - `providerTimeouts` object: Per-request provider timeouts in ms, keyed by provider slug for BYOK credentials.
      - `byok` object
    - `selector` 'cost' | 'tps' | 'ttft': For kind=router: how to order candidates. Absent means declared order.
    - `selectorOptions` object: For kind=router: option slices keyed by selector name; each selector owns its slice's shape.
      - `cost` AiGatewayRouterSelectorOptionBag: For kind=router: option slices keyed by selector name; each selector owns its slice's shape.
      - `tps` AiGatewayRouterSelectorOptionBag: For kind=router: option slices keyed by selector name; each selector owns its slice's shape.
      - `ttft` AiGatewayRouterSelectorOptionBag: For kind=router: option slices keyed by selector name; each selector owns its slice's shape.
    - `serviceTier` 'fast' | 'flex' | 'priority': Service tier for providers that support it.
    - `sort` 'cost' | 'latency' | 'price' | 'throughput' | 'tps' | 'ttft': Rank eligible providers by an attribute.
    - `speed` 'fast': Only use fastest providers with short timeouts.
    - `status` string, required: UI lifecycle status: draft, active, or archived.
    - `updatedAt` number, required: Last update timestamp (epoch ms).
    - `updatedBy` string: User or app id that last updated this VMC.
    - `virtualModelSlug` string, required: Client-facing alias used as the model slug in Gateway calls.
    - `visibility` string: Visibility in listings: public, internal, or stealth.
    - `zeroDataRetention` false | true: Only use providers with zero data retention.

## Other responses

- `400`: One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `410`
- `500`

## Changes

- **2026-10-15** `8939e3983223`: 1 info
  - added the new optional `query` request parameter `includeArchived`
- **2026-09-30** `6f68095b42b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/api/changes/ai-gateway/virtual-model-configs/list/get.md)

---

[API](https://skmtc.dev/vercel/apis/api.md) - [All operations](https://skmtc.dev/vercel/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/api/revisions/4a06e85c2848?raw)