AI Gateway REST API Reference

For sending inference requests, the AI SDK lets you interact with AI Gateway from TypeScript or Python. You can also send requests through the chat completions, responses, Anthropic Messages, or OpenResponses APIs.

AI Gateway exposes a REST API for looking up usage and generations, querying spend reports, and discovering models. This page is the canonical reference for those endpoints. The AI SDK AI Gateway provider also exposes TypeScript APIs for the same data, which you can use as an alternative to calling the REST endpoints directly.

https://ai-gateway.vercel.sh/v1

Most endpoints require authentication. The exceptions are noted on each endpoint.

Pass an AI Gateway API key in the Authorization header. AI Gateway infers the team from the key.

Authorization: Bearer <api_key>

On Vercel deployments, you can pass the Vercel OIDC token in the Authorization header instead. The token is generated automatically per project.

GET /v1/models

Lists every model available through AI Gateway, including reasoning controls, supported parameters, pricing, and modalities. Follows the OpenAI models API format. No authentication required.

For the AI SDK equivalent, see Dynamic Model Discovery.

const response = await fetch('https://ai-gateway.vercel.sh/v1/models');
const { data: models }: { data: Array<{ id: string; name: string }> } =
  await response.json();
 
models.forEach((model) => {
  console.log(`${model.id}: ${model.name}`);
});

For TypeScript, Python, and cURL examples that filter reasoning models and inspect their controls, see Discover model reasoning support.

{
  "object": "list",
  "data": [
    {
      "id": "google/gemini-3.1-pro-preview",
      "object": "model",
      "created": 1755815280,
      "released": 1763424000,
      "owned_by": "google",
      "name": "Gemini 3.1 Pro Preview",
      "description": "This model improves upon Gemini 2.5 Pro and is catered towards challenging tasks, especially those involving complex reasoning or agentic workflows.",
      "context_window": 1000000,
      "max_tokens": 64000,
      "type": "language",
      "tags": ["file-input", "tool-use", "reasoning", "vision"],
      "pricing": {
        "input": "0.000002",
        "output": "0.000012",
        "input_cache_read": "0.0000002",
        "input_cache_write": "0.000002"
      }
    }
  ]
}

The catalog doesn't expose a structured reasoning default. Missing controls or budget bounds mean unspecified metadata, not unsupported reasoning or an unlimited budget. The controls describe model capabilities; each request format has its own fields and accepted values.

Pass include_availability with an authenticated request to annotate the catalog with each model's eligibility under your team's configuration:

GET /v1/models?include_availability

Eligibility reflects your team's stored defaults: model and provider allowlists, routing rules, stored BYOK credentials, virtual model configuration, plan restrictions, and rate-limit configuration. It does not evaluate request-supplied credentials, request-selected providers, live provider health, or account state beyond the request-level result below.

const response = await fetch(
  'https://ai-gateway.vercel.sh/v1/models?include_availability',
  { headers: { Authorization: `Bearer ${process.env.AI_GATEWAY_API_KEY}` } },
);
const { data: models } = await response.json();
 
const eligible = models.filter(
  (model) => model.model_eligibility?.status === 'eligible',
);

Each model row gains a model_eligibility field, and the response adds request-level fields:

A model can serve a request when its status is eligible and the matching request_context_availability runtime is available. Treat unknown as neither approval nor denial; it means a dependency could not be resolved.

Annotated requests share a per-team rate limit. A blocked request returns 429 with Retry-After: 60.

GET /v1/models/{creator}/{model}/endpoints

Returns every provider endpoint serving a specific model, along with per-endpoint pricing, capabilities, and supported parameters. No authentication required.

const response = await fetch(
  'https://ai-gateway.vercel.sh/v1/models/google/gemini-3.1-pro-preview/endpoints',
);
const {
  data,
}: {
  data: {
    name: string;
    endpoints: Array<{ provider_name: string; context_length: number }>;
  };
} = await response.json();
 
console.log(`Model: ${data.name}`);
data.endpoints.forEach((endpoint) => {
  console.log(`  ${endpoint.provider_name}: ${endpoint.context_length} tokens`);
});

{
  "data": {
    "id": "google/gemini-3.1-pro-preview",
    "name": "Gemini 3.1 Pro Preview",
    "created": 1755815280,
    "released": 1763424000,
    "description": "This model improves upon Gemini 2.5 Pro and is catered towards challenging tasks, especially those involving complex reasoning or agentic workflows.",
    "architecture": {
      "tokenizer": null,
      "instruct_type": null,
      "modality": "text+image+file→text",
      "input_modalities": ["text", "image", "file"],
      "output_modalities": ["text"]
    },
    "endpoints": [
      {
        "name": "google | google/gemini-3.1-pro-preview",
        "model_name": "Gemini 3.1 Pro Preview",
        "context_length": 1000000,
        "pricing": {
          "prompt": "0.000002",
          "completion": "0.000012",
          "input_cache_read": "0.0000002",
          "input_cache_write": "0.000002"
        },
        "provider_name": "google",
        "max_completion_tokens": 64000,
        "supported_parameters": ["max_tokens", "temperature", "tools", "reasoning"],
        "status": 0,
        "uptime_last_15m": 100,
        "uptime_last_1h": 99.8,
        "uptime_last_1d": 99.6,
        "throughput_last_1h": { "p50": 67, "p95": 69.85 },
        "latency_last_1h": { "p50": 2292, "p95": 2685 },
        "supports_implicit_caching": false
      }
    ]
  }
}

For more on the uptime and metrics fields, see Uptime and Status and Metrics.

Some models have tiered pricing based on context size. When tiered pricing applies, the *_tiers arrays contain pricing tiers:

GET /v1/credits

Returns the team's current AI Gateway Credits balance and lifetime spend.

For the AI SDK equivalent, see Credit Usage.

const apiKey = process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN;
 
const response = await fetch('https://ai-gateway.vercel.sh/v1/credits', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});
 
const credits = await response.json();
console.log(credits);

import os
import requests
 
api_key = os.getenv("AI_GATEWAY_API_KEY") or os.getenv("VERCEL_OIDC_TOKEN")
 
response = requests.get(
    "https://ai-gateway.vercel.sh/v1/credits",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)
 
credits = response.json()
print(credits)

curl -X GET "https://ai-gateway.vercel.sh/v1/credits" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"

{
  "balance": "95.50",
  "total_used": "4.50"
}

• balance: Remaining credit balance, in USD
• total_used: Total credits used to date, in USD

GET /v1/generation?id={generation_id}

Returns detailed information about a specific generation, including cost, latency, and token usage. Much of this data is also returned in providerMetadata on the chat completion response.

For a complete request-and-lookup example with the AI SDK, see Look up a generation with the AI SDK.

Usage events are ingested asynchronously, so a lookup issued immediately after the generation completes returns Usage event not found rather than the record. Allow a few seconds, and treat that response as "not yet" rather than "never" when polling.

For the AI SDK equivalent, see Generation Lookup.

• id (required): The generation ID to look up. Format: gen_<ulid>.

const generationId = 'gen_01ARZ3NDEKTSV4RRFFQ69G5FAV';
 
const response = await fetch(
  `https://ai-gateway.vercel.sh/v1/generation?id=${generationId}`,
  {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${process.env.AI_GATEWAY_API_KEY}`,
      'Content-Type': 'application/json',
    },
  },
);
 
const generation = await response.json();
console.log(generation);

import os
import requests
 
generation_id = 'gen_01ARZ3NDEKTSV4RRFFQ69G5FAV'
 
response = requests.get(
    f"https://ai-gateway.vercel.sh/v1/generation?id={generation_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('AI_GATEWAY_API_KEY')}",
        "Content-Type": "application/json",
    },
)
 
generation = response.json()
print(generation)

curl -X GET "https://ai-gateway.vercel.sh/v1/generation?id=gen_01ARZ3NDEKTSV4RRFFQ69G5FAV" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"

{
  "data": {
    "id": "gen_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "total_cost": 0.00123,
    "market_cost": 0.0011,
    "surcharge_cost": 0.00013,
    "gateway_cost": 0.00123,
    "upstream_inference_cost": 0,
    "usage": 0.00123,
    "created_at": "2026-05-22T00:00:00.000Z",
    "model": "anthropic/claude-opus-5",
    "is_byok": false,
    "provider_name": "anthropic",
    "streamed": true,
    "finish_reason": "stop",
    "latency": 200,
    "generation_time": 1500,
    "tokens_prompt": 100,
    "tokens_completion": 50,
    "native_tokens_prompt": 100,
    "native_tokens_completion": 50,
    "native_tokens_reasoning": 0,
    "native_tokens_cached": 0,
    "native_tokens_cache_creation": 0,
    "billable_web_search_calls": 0
  }
}

• id: The generation ID
• total_cost: Total cost in USD for this generation debited from your gateway balance, including any surcharges (for example, Zero Data Retention or Custom Reporting writes). Does not include cost of BYOK requests.
• market_cost: Cost of this generation at market list inference rates. Omitted when not recorded for the generation.
• surcharge_cost: Total surcharges applied to this generation (for example, Zero Data Retention or Custom Reporting writes)
• gateway_cost: Total amount debited from your AI Gateway balance for this generation. Same as total_cost.
• upstream_inference_cost: Market list price for BYOK that the provider would have charged for the inference. Non-zero only for BYOK generations. 0 otherwise.
• usage: Same as total_cost.
• created_at: ISO 8601 timestamp when the generation was created
• model: Model identifier used for this generation
• is_byok: Whether this generation used Bring Your Own Key (BYOK) credentials
• provider_name: The provider that served this generation
• streamed: Whether this generation used streaming
• finish_reason: Why the generation ended (for example, stop, length, content_filter, tool_calls)
• latency: Time to first token in milliseconds
• generation_time: Total generation time in milliseconds
• tokens_prompt: Number of prompt tokens
• tokens_completion: Number of completion tokens
• native_tokens_prompt: Native prompt tokens (provider-specific)
• native_tokens_completion: Native completion tokens (provider-specific)
• native_tokens_reasoning: Reasoning tokens used
• native_tokens_cached: Cached input tokens read
• native_tokens_cache_creation: Cache creation tokens written
• billable_web_search_calls: Number of billable web search calls performed during this generation

Use the Custom Reporting API to break down spend and usage by model, user, tag, provider, or credential type. For concepts, how to attach tags and user IDs to requests, querying with the AI SDK, and the full response field reference, see the Custom Reporting page.

GET /v1/report

Returns aggregated spend over a date range. The team is inferred from the API key or OIDC token. Hobby and Pro-trial plans cannot use this endpoint.

For the AI SDK equivalent, see Querying Spend Reports.

Dates are inclusive (both start_date and end_date are included) and in UTC.

API key names are not unique, so use api_key_id when filtering by API key.

curl "https://ai-gateway.vercel.sh/v1/report?start_date=2026-01-01&end_date=2026-01-31&group_by=model" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"

For the full response shape, sample JSON, and the per-field reference (which grouping fields appear with which group_by value, plus all metric fields), see Response format and Response fields on the Custom Reporting page.

Errors return a JSON body with an error field. Some endpoints additionally include a type discriminator on the error object.

{
  "error": {
    "message": "Invalid request body",
    "type": "invalid_request_error"
  }
}