---
title: list-virtual-model-configs
product: vercel
url: /docs/rest-api/api-ai-gateway/list-virtual-model-configs
canonical_url: "https://vercel.com/docs/rest-api/api-ai-gateway/list-virtual-model-configs"
last_updated: 2026-09-01
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about list-virtual-model-configs on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# List virtual model configs

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

List virtual model configs. With `ownerId`, returns all of that team's VMCs. Without it, pages through VMCs across all teams (newest-first, `limit`/`cursor`).

## Authentication

**bearerToken**: HTTP bearer

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `ownerId` | string | No |  |
| `limit` | integer. min: 1 | No |  |
| `cursor` | string | No |  |
| `teamId` | string | No | The Team identifier to perform the request on behalf of. |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Example request

### TypeScript

```typescript
const response = await fetch('https://api.vercel.com/v1/ai-gateway/virtual-model-configs/list?ownerId=string&limit=123&cursor=string&teamId=string&slug=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
```

### Next.js

```typescript
'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v1/ai-gateway/virtual-model-configs/list?ownerId=string&limit=123&cursor=string&teamId=string&slug=string', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    next: { revalidate: 3600 }
  });

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
}
```

### cURL

```bash
curl -X GET 'https://api.vercel.com/v1/ai-gateway/virtual-model-configs/list?ownerId=string&limit=123&cursor=string&teamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

## Example response

```json
{
  "virtualModelConfigs": [
    {
      "ownerId": "example_id",
      "virtualModelSlug": "string",
      "displayName": "Example Name",
      "description": "string",
      "deleted": "false",
      "status": "string",
      "visibility": "string",
      "updatedBy": "string",
      "kind": "string",
      "baseUrl": "https://example.com",
      "instanceId": "example_id",
      "providerOrder": [],
      "providerOnly": [],
      "providerOptions": "value",
      "inferenceRegion": {
        "providers": "value",
        "scope": "global",
        "geoRegion": "string",
        "providerRegion": "example_id"
      },
      "modelSlug": "string",
      "models": [],
      "selector": "cost",
      "requires": [],
      "byokCredentialIds": [],
      "observabilityTags": [],
      "sort": "cost",
      "has": [],
      "caching": "auto",
      "serviceTier": "fast",
      "providerTimeouts": {
        "byok": "value"
      },
      "zeroDataRetention": "false",
      "hipaaCompliant": "false",
      "disallowPromptTraining": "false",
      "speed": "fast",
      "allowFallbackFromFast": "false",
      "createdAt": "123",
      "updatedAt": "123"
    }
  ],
  "cursor": "string"
}
```

## Responses

### 200: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "cursor",
    "virtualModelConfigs"
  ],
  "properties": {
    "virtualModelConfigs": {
      "type": "array",
      "description": "The page of VMCs.",
      "items": {
        "type": "object",
        "description": "Public response shape for virtual model configs. Used so OpenAPI generation can avoid ElectroDB's recursive EntityItem types.",
        "required": [
          "createdAt",
          "deleted",
          "kind",
          "ownerId",
          "status",
          "updatedAt",
          "virtualModelSlug"
        ],
        "properties": {
          "ownerId": {
            "type": "string",
            "description": "Team (owner) that owns this VMC."
          },
          "virtualModelSlug": {
            "type": "string",
            "description": "Client-facing alias used as the model slug in Gateway calls."
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable name for UI."
          },
          "description": {
            "type": "string",
            "description": "Optional description for UI."
          },
          "deleted": {
            "type": "boolean",
            "description": "Whether this VMC is soft-deleted.",
            "enum": [
              false,
              true
            ]
          },
          "status": {
            "type": "string",
            "description": "UI lifecycle status: draft, active, or archived."
          },
          "visibility": {
            "type": "string",
            "description": "Visibility in listings: public, internal, or stealth."
          },
          "updatedBy": {
            "type": "string",
            "description": "User id that last updated this VMC."
          },
          "kind": {
            "type": "string",
            "description": "VMC kind: alias, relay, or router."
          },
          "baseUrl": {
            "type": "string",
            "description": "For kind=relay: URL the gateway forwards requests to as a transparent proxy."
          },
          "instanceId": {
            "type": "string",
            "description": "The concrete model-provider instance this VMC resolves to."
          },
          "providerOrder": {
            "type": "array",
            "description": "Ordered list of providers to try as fallbacks on failure."
          },
          "providerOnly": {
            "type": "array",
            "description": "Restrict routing to only these providers."
          },
          "providerOptions": {
            "type": "object",
            "description": "Arbitrary per-provider AI SDK options, keyed by gateway provider slug."
          },
          "inferenceRegion": {
            "type": "object",
            "description": "Region pinned on the VMC for system-credential routing (alias/router only)."
          },
          "modelSlug": {
            "type": "string",
            "description": "Canonical model slug this VMC maps to (e.g. \"creator/model\"). Not used by kind=router."
          },
          "models": {
            "type": "array",
            "description": "For kind=router: ordered candidates, model slugs or router references. Otherwise: fallback models."
          },
          "selector": {
            "type": "string",
            "description": "For kind=router: how to order candidates.",
            "enum": [
              "cost",
              "priority",
              "tps",
              "ttft"
            ]
          },
          "requires": {
            "type": "array",
            "description": "For kind=router: capability tags a candidate must have."
          },
          "byokCredentialIds": {
            "type": "array",
            "description": "BYOK credential IDs allowed for this VMC."
          },
          "observabilityTags": {
            "type": "array",
            "description": "Observability tags attached to requests through this VMC."
          },
          "sort": {
            "type": "string",
            "description": "Rank eligible providers by an attribute.",
            "enum": [
              "cost",
              "latency",
              "price",
              "throughput",
              "tps",
              "ttft"
            ]
          },
          "has": {
            "type": "array",
            "description": "Limit providers to those with these features."
          },
          "caching": {
            "type": "string",
            "description": "Use caching if available.",
            "enum": [
              "auto"
            ]
          },
          "serviceTier": {
            "type": "string",
            "description": "Service tier for providers that support it.",
            "enum": [
              "fast",
              "flex",
              "priority"
            ]
          },
          "providerTimeouts": {
            "type": "object",
            "description": "Per-request provider timeouts in ms, keyed by provider slug for BYOK credentials."
          },
          "zeroDataRetention": {
            "type": "boolean",
            "description": "Only use providers with zero data retention.",
            "enum": [
              false,
              true
            ]
          },
          "hipaaCompliant": {
            "type": "boolean",
            "description": "Only use HIPAA-compliant providers.",
            "enum": [
              false,
              true
            ]
          },
          "disallowPromptTraining": {
            "type": "boolean",
            "description": "Only use providers that will not train on your prompts.",
            "enum": [
              false,
              true
            ]
          },
          "speed": {
            "type": "string",
            "description": "Only use fastest providers with short timeouts.",
            "enum": [
              "fast"
            ]
          },
          "allowFallbackFromFast": {
            "type": "boolean",
            "description": "Allow fallback from fast to standard providers on failure.",
            "enum": [
              false,
              true
            ]
          },
          "createdAt": {
            "type": "number",
            "description": "Creation timestamp (epoch ms)."
          },
          "updatedAt": {
            "type": "number",
            "description": "Last update timestamp (epoch ms)."
          }
        }
      }
    },
    "cursor": {
      "type": "string",
      "description": "Cursor for the next page, or null when no more pages remain.",
      "nullable": true
    }
  }
}
```

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

### 410: No description

### 500: No description

---

## Related

- [api-ai-gateway endpoints](/docs/rest-api#api-ai-gateway)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)