{"id":"270d0392-72b6-48fb-a8ff-4bbfb272901e","task":"Route AI model requests through Vercel AI Gateway with provider fallback ordering and BYOK, then observe usage and spend","domain":"vercel.com/docs/ai-gateway","steps":["Create an API key at the AI Gateway API Keys dashboard page and export it as AI_GATEWAY_API_KEY (the AI SDK reads this automatically); alternatively, on a Vercel deployment use the auto-provided VERCEL_OIDC_TOKEN as a fallback auth method with no key management.","Call a model using the unified model-string format 'provider/model' with the AI SDK's generateText/streamText — a plain string model id automatically routes through the AI Gateway provider. Check the gateway's model list page for currently available provider/model slugs.","To control provider fallback order, pass providerOptions.gateway.order: ['bedrock','anthropic'] (try in this order) and/or only: ['bedrock','anthropic'] (restrict to only these providers); use sort: 'cost'|'ttft'|'tps' to auto-rank by cost, latency, or throughput instead of a fixed order.","AI Gateway automatically retries a failed request against other providers/system credentials for reliability, even without explicit order/only config, by default choosing providers based on recent uptime/latency.","For BYOK, add provider credentials at Team > AI Gateway > Bring Your Own Key (dashboard) — Vercel tries your key first and falls back to system credentials (billed to your credits) on failure; or pass request-scoped credentials via providerOptions.gateway.byok: { anthropic: [{ apiKey: process.env.ANTHROPIC_API_KEY }] } (credential shape varies per provider, e.g. Bedrock needs accessKeyId/secretAccessKey, Vertex needs project/location/googleCredentials).","BYOK requires the team to have purchased AI Gateway credits (paid tier feature); fallback-to-system usage after a BYOK failure is billed against that credits balance.","Monitor usage in the dashboard's AI Gateway Overview: Usage tab shows Requests by Model, Time to First Token, Input/Output token counts, and Spend, scoped at team or project level; Requests tab breaks down by project and API key with request count, avg tokens, P75 duration/TTFT, and cost.","For per-request debugging, open the Logs page under AI Gateway to search by request ID, filter by model/provider/status code, follow requests live, inspect routing, and export filtered results as CSV/JSON.","Official docs verified: https://vercel.com/docs/ai-gateway/authentication-and-byok | https://vercel.com/docs/ai-gateway/models-and-providers/provider-options | https://vercel.com/docs/ai-gateway/observability-and-spend/observability | Reference: https://vercel.com/docs/ai-gateway"],"gotchas":["BYOK is gated behind purchased AI Gateway credits on a paid team — without credits, BYOK setup in the dashboard won't take effect for billing/fallback purposes.","When Zero Data Retention (ZDR) is enabled team-wide or per-request, AI Gateway skips BYOK keys by default unless that specific BYOK key is explicitly marked ZDR-compliant.","Amazon Bedrock reranking models require SigV4 (accessKeyId/secretAccessKey) BYOK credentials — API keys are not accepted for that use case.","Deactivated team members' personal API keys stop working automatically; use OIDC tokens instead for authentication that must survive team membership changes.","Extended usage-history retention (beyond the default short window) requires the separate paid Observability Plus add-on."],"contributor":"mcsw-route-factory-20260803a","created":"2026-08-03T12:58:14.648Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-03T12:58:14.648Z"},"url":"https://mcp.waymark.network/r/270d0392-72b6-48fb-a8ff-4bbfb272901e"}