skilld
All skills
vercel-labs avatar

/ai-gateway

@8fd4644 official
by Vercel Labsvercel-labs/vercel-plugin295 stars
64

Vercel AI Gateway guidance for setup, model discovery, authentication, routing, fallbacks, BYOK, budgets, spend reporting, observability, compatible APIs, and coding-agent configuration. Use when adding AI Gateway to an app, migrating provider calls, choosing models or providers, debugging gateway requests, or running `vercel ai-gateway` commands.

  • 5 files
  • 49.1 KB
  • Updated last week
  • GitHub

Ask your Agent

Use this Skill: https://skilld.dev/gh/vercel-labs/vercel-plugin/ai-gateway

This session only. Nothing lands on disk.

referencesspend-observability.md

≈2.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Credits, budgets, reporting, and observability

Use this reference for AI Gateway Credits, spend caps, usage reporting, request logs, and debugging. Read current docs before editing billing or spend controls.

AI Gateway Credits and pricing

AI Gateway adds no platform markup to provider pricing, and some models are priced below provider list for every team; browse current ones at https://vercel.com/ai-gateway/models?discount=true. Volume commitments can negotiate custom discounts with invoice payment. Requests draw on AI Gateway Credits unless BYOK credentials are used. Docs: https://vercel.com/docs/ai-gateway/pricing/discounts

  • A team needs a valid payment method to unlock free AI Gateway Credits. The gateway returns customer_verification_required with an action link when verification is missing.
  • Free-tier requests use a subset of models and have lower per-model rate limits. Exceeding one returns 429; buying credits moves the team to the paid tier and raises limits.
  • A request that exceeds the balance fails with 402 and insufficient_funds. BYOK requests also require a positive balance so fallback providers remain available.
  • Credits support manual top-up and auto top-up. Some opt-in extras bill separately: Custom Reporting writes and queries, Trace Drains, and team-wide compliance or provider-restriction policies.

Check the pricing page for the current free-credit amount and tiers instead of hardcoding it. Docs: https://vercel.com/docs/ai-gateway/pricing

Budgets

A budget caps AI Gateway spend at one of four scopes:

Scope Meters
Team Every request across the team
Project Requests authenticated by that project's OIDC tokens
API key Requests using that one key
User Requests using keys attributed to that member

Budgets stack. A request must pass every budget in scope, and one exhausted budget rejects it even when the others have room. Exceeded budgets reject further requests with HTTP 402 and type quota_for_entity_exceeded until the budget resets or its limit is raised. A budget is a soft cap: the request that crosses the limit completes.

Refresh periods reset at UTC boundaries: daily at midnight, weekly on Monday, monthly on the first of the month. none never resets.

Default budgets

Each of project, API key, and user scopes can have one default that covers every covered resource without its own budget:

  • The default applies immediately to existing and future resources in that scope.
  • Each covered resource gets its own allowance; the limit is per resource, not split across them.
  • A custom budget always wins over the default.
  • Removing a default lifts the cap from every covered resource; only a wider team budget still applies.

Spend alerts

Custom budgets can email on 50%, 75%, or 100% of the limit, at most once per period per threshold. Recipients depend on scope: team and project budgets email team owners and members with the Billing role, an API key budget emails the key's creator, and a user budget emails that member. Alerts are informational; a threshold below 100% never blocks requests.

Default budgets do not send spend alerts; set a custom budget on a resource to get alerts for it.

BYOK spend is metered separately and does not count toward any budget.

CLI and API

The Vercel CLI manages budgets per scope. set creates or updates, list shows every scope's limit and spend, inspect shows one scope, and remove lifts a cap (falling back to the scope's default when one exists). Defaults get their own defaults subcommand:

vercel ai-gateway budgets set team --limit 500 --refresh-period monthly
vercel ai-gateway budgets set project my-project --limit 200
vercel ai-gateway budgets set api-key my-key --limit 50
vercel ai-gateway budgets defaults set api-key --limit 50 --refresh-period monthly
vercel ai-gateway budgets inspect team
vercel ai-gateway budgets list

Check vercel ai-gateway budgets set --help for the current flag set before scripting.

Budget changes take effect after a short delay, typically tens of seconds and up to about 5 minutes for an actively used key.

Docs: https://vercel.com/docs/ai-gateway/observability-and-spend/budgets and https://vercel.com/docs/cli/ai-gateway#budgets

Request authentication

Team budgets count every request. Project budgets apply only to OIDC-authenticated requests from that project's deployments. API key and user budgets apply to key usage. BYOK requests are metered but never counted against a limit. Read the budgets page before changing attribution or defaults; metering is not retroactive for a re-created budget.

Spend attribution and permissions

Each API key is attributed to the team or to the member who created it. Only member-attributed keys count toward a user budget; OIDC tokens, personal access tokens, and app tokens never do. Attribution is editable: https://vercel.com/docs/ai-gateway/authentication-and-byok/api-keys#spend-attribution

Every team role except Contributor can view budgets. An Owner can grant a member the AI Gateway Budget Manager permission, which covers budget writes at every scope except API key budgets, which follow key-editing permission.

Observability

The AI Gateway Overview shows usage, spend, time to first token, and token counts by model, plus request summaries by project and API key. AI Traces and Trace Drains cover OpenTelemetry tracing and export for Pro and Enterprise (https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains).

For individual requests, use the Logs page. It lists every request and asynchronous job newest first with status, model, provider, usage, cost, duration, and authentication, and supports filters for status, model, provider, authentication, routing, modality, latency, tokens, cost, and date range. Filters live in the URL, so a filtered view can be shared. Live mode tails new requests as they arrive; requests take about 90 seconds to fully ingest. Logs also exist at project scope under /[team]/[project]/ai-gateway/logs, and the page copies visible rows or exports loaded rows as CSV or JSON.

One request's details panel shows every provider attempt, including retries, credential source, time to first token, timing spans, status, and provider response, plus usage and cost breakdowns. Routing attempt details are kept for 30 days; the list allows up to 36 days.

Docs: https://vercel.com/docs/ai-gateway/observability-and-spend/logs and https://vercel.com/docs/ai-gateway/observability-and-spend/observability

Custom Reporting

The Custom Reporting API aggregates usage by model, user, tag, provider, credential type, ZDR status, or API key name, with filters for each dimension and day- or hour-level granularity. It requires a Pro or Enterprise plan and bills writes and queries.

Attach user and/or tags to requests through providerOptions.gateway (AI SDK) or extra_body.providerOptions.gateway (Python SDKs), or through the ai-reporting-user and ai-reporting-tags headers when a proxy stamps context without changing application code.

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"

Results can take a few minutes to appear. The AI SDK exposes equivalent helpers, such as gateway.getSpendReport() and gateway.getGenerationInfo(); confirm names against the installed package.

Docs: https://vercel.com/docs/ai-gateway/observability-and-spend/custom-reporting

Usage and billing endpoints

Two REST endpoints cover balance and per-request cost without opening the dashboard:

  • GET /v1/credits returns the team's remaining credit balance and lifetime spend.
  • GET /v1/generation returns cost, latency, finish reason, and token usage for one generation.

Every response carries its generation ID: the id field on a chat completion, injected into the first chunk of a stream, and providerMetadata.gateway.generationId in the AI SDK. Capture it when the application may need a cost lookup later.

Docs: https://vercel.com/docs/ai-gateway/observability-and-spend/usage and the REST API reference at https://vercel.com/docs/ai-gateway/sdks-and-apis/rest-api

Debugging checklist

  1. Find the request in AI Gateway Logs by request ID, model, status, or time range.
  2. Check authentication: the row names the API key, OIDC project, app token, or personal access token used.
  3. Read the routing cards for every provider attempt and their statuses.
  4. Compare usage and cost against the budget and credit balance.
  5. For a failed request, match the status against the first-request error table before changing routing or credentials.
  6. For recurring spend patterns, query Custom Reporting by model, tag, user, or credential type rather than reading individual logs one at a time.

Source: SKILL.md on GitHub

Third-party checks

No third-party reports yet.

Provenance

Signed by skilld at 8fd4644. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 14 hours ago.

Activeupdated last week

Capability

Other metadata
summary
Set up and operate Vercel AI Gateway with current models, correct authentication, routing, spend controls, and verification.
metadata
{
  "priority": 7,
  "docs": [
    "https://vercel.com/docs/ai-gateway",
    "https://vercel.com/docs/ai-gateway/getting-started",
    "https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway"
  ],
  "sitemap": "https://vercel.com/docs/sitemap.md",
  "pathPatterns": [],
  "importPatterns": [
    "ai",
    "@ai-sdk/gateway"
  ],
  "bashPatterns": [
    "\\bvercel\\s+ai-gateway\\b",
    "\\bvercel\\s+env\\s+pull\\b",
    "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\bbun\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\byarn\\s+add\\s+[^\\n]*@ai-sdk/gateway\\b"
  ],
  "promptSignals": {
    "phrases": [
      "ai gateway",
      "vercel ai gateway",
      "ai-gateway",
      "ai-gateway.vercel.sh"
    ],
    "allOf": [
      [
        "model",
        "routing"
      ],
      [
        "provider",
        "failover"
      ],
      [
        "gateway",
        "budget"
      ],
      [
        "gateway",
        "logs"
      ],
      [
        "gateway",
        "oidc"
      ],
      [
        "coding",
        "gateway"
      ]
    ],
    "anyOf": [
      "provider ordering",
      "model fallback",
      "byok",
      "spend tracking",
      "gateway key",
      "credit balance",
      "safety identifier",
      "reasoning effort",
      "tool calling",
      "structured outputs"
    ],
    "noneOf": [
      "cloudflare ai gateway",
      "aws api gateway"
    ],
    "minScore": 6
  }
}
validate
[
  {
    "pattern": "\\bclaude-(sonnet|opus|haiku)-\\d+-\\d+\\b",
    "message": "Claude model version uses a hyphen where the AI Gateway slug uses a dot. Fetch /v1/models and use the returned provider/model ID.",
    "severity": "error"
  },
  {
    "pattern": "gateway\\(['\"][^'\"/]+['\"]\\)",
    "message": "AI Gateway model string is missing its provider prefix. Fetch /v1/models and use a provider/model ID.",
    "severity": "error"
  },
  {
    "pattern": "(OPENAI_API_KEY|ANTHROPIC_API_KEY|GOOGLE_API_KEY)",
    "message": "Provider key detected. AI Gateway request authentication uses AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN; provider keys belong only in an intentional BYOK configuration.",
    "severity": "recommended",
    "skipIfFileContains": "[Bb][Yy][Oo][Kk]|providerOptions\\s*:\\s*\\{[^}]*gateway"
  },
  {
    "pattern": "gateway\\s*:\\s*\\{[^}]*cacheControl",
    "message": "AI Gateway does not cache whole responses through cacheControl. Use caching: 'auto' for provider prompt caching and verify the current caching docs.",
    "severity": "error"
  },
  {
    "pattern": "ANTHROPIC_BASE_URL\\s*=\\s*[\"']?https://ai-gateway\\.vercel\\.sh",
    "message": "Claude Code through AI Gateway needs ANTHROPIC_API_KEY set to an empty value and the gateway key in ANTHROPIC_AUTH_TOKEN. A non-empty ANTHROPIC_API_KEY is used instead of the gateway token.",
    "severity": "recommended",
    "skipIfFileContains": "ANTHROPIC_AUTH_TOKEN"
  }
]
chainTo
[
  {
    "pattern": "from\\s+['\"]ai['\"]|require\\(['\"]ai['\"]\\)|\\b(generateText|streamText|ToolLoopAgent)\\b",
    "targetSkill": "ai-sdk",
    "message": "AI SDK code detected. Load the AI SDK skill and read the installed package docs before writing or changing SDK code."
  }
]
retrieval
{
  "aliases": [
    "model router",
    "ai proxy",
    "provider failover",
    "llm gateway",
    "gateway credits"
  ],
  "intents": [
    "add Vercel AI Gateway to an application",
    "route AI models across providers",
    "configure provider or model fallbacks",
    "authenticate AI Gateway requests",
    "track AI model costs and set budgets",
    "debug AI Gateway requests and routing",
    "connect coding agents to AI Gateway",
    "find a model by modality, capability, price, or data retention",
    "check AI Gateway credit balance or generation cost",
    "configure reasoning or extended thinking across providers and API formats",
    "add tool calling or function calling across API formats",
    "get structured JSON output matching a schema",
    "send images or PDFs to a model"
  ],
  "entities": [
    "AI Gateway",
    "AI Gateway Credits",
    "providerOptions.gateway",
    "AI_GATEWAY_API_KEY",
    "VERCEL_OIDC_TOKEN",
    "model routing",
    "provider failover",
    "BYOK",
    "spend reporting",
    "safetyIdentifier",
    "Usage & Billing API"
  ]
}

README badge

README badge for vercel-labs/vercel-plugin/ai-gateway