Skip to main content

Gateway

Mastra Gateway lets you call models from many providers through one managed API. It centralizes credentials, fails over between providers, controls spend, and records the cost of every request. You don't have to run your own proxy or routing layer.

  • One key, many providers: Call OpenAI, Anthropic, Google, and other providers with one Gateway key and a provider/model model ID.
  • Routing and failover: Gateway retries eligible failures on another route before any output reaches your client.
  • Bring your own key (BYOK): Send traffic through your own provider accounts.
  • Usage and spend controls: Every request records its attempts and cost, and keys can be limited by model.
  • Gateway tools: Add web search to tool-capable chat models with one tool entry.

Gateway uses the OpenAI and Anthropic wire formats. To use it with an existing SDK or framework, change the base URL and the API key. The model ID names the model, and Gateway routing picks the provider that serves it:

src/mastra/agents/assistant.ts
import { Agent } from '@mastra/core/agent'

export const assistant = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant.',
model: 'mastra/openai/gpt-6.1-sol',
})

Connect from your stack
Direct link to Connect from your stack

If you useConnect with
Mastra frameworkA mastra/provider/model model ID and the MASTRA_GATEWAY_API_KEY environment variable. See Integrations.
AI SDKThe OpenAI-compatible or Anthropic provider with the Gateway base URL. See Integrations.
OpenAI SDK (TypeScript or Python)baseURL (TypeScript) or base_url (Python) set to https://gateway-api.mastra.ai/v1. See Chat Completions and Responses.
Anthropic SDKbaseURL set to https://gateway-api.mastra.ai, without /v1. See Anthropic Messages.
LangGraph, Deep Agents, or Pydantic AIThe framework's OpenAI-compatible model client. See Integrations.
Any other languageAny HTTP client that can call the OpenAI or Anthropic API.

What Gateway handles
Direct link to What Gateway handles

You pay for the attempt that served your request. If a failed attempt on a token endpoint has a known provider cost, that cost is charged without markup, even when every attempt fails. BYOK requests are billed by your provider, not from Mastra credit. Your provider's own limits and behavior apply to BYOK requests, and they don't fail over. Gateway doesn't store prompts or completions.

note

Conversation memory is a separate product. To give agents memory, see Memory.

Choose how to start
Direct link to Choose how to start

Configure and operate Gateway
Direct link to Configure and operate Gateway

Browse every model, its ID, and its price in the model catalog. To list models from code, call GET /v1/models. For answers to common questions about credits, keys, and errors, see the FAQ.

FAQ
Direct link to FAQ

How do I get started?

Add credits in Billing at projects.mastra.ai, create a key, and follow the Quickstart.

Why do I get 402?

insufficient_credit means your balance can't cover the request's credit reservation. This includes bursts of concurrent requests that together exceed the balance. spend_limit_reached means a key or organization budget was reached. A 402 can also mean the organization's billing configuration doesn't support Gateway usage. Add credits, turn on auto top-up, raise the cap, or contact support about billing setup. See Usage, pricing, and limits.

Why do I get 401 with a key that starts with msk_?

msk_ keys belong to the previous Memory Gateway. Requests with these keys are routed to Memory Gateway, not the current Gateway API, so they fail against current endpoints and features. Memory Gateway shuts down on December 31, 2026. Create a new msk-gateway- key. See Migrate.

Does Gateway store my prompts or conversations?

No. Usage logs record model, provider, tokens, and cost, not content. For agent memory, see Memory.

Which provider served my request?

Check the x-gateway-provider response header, or find the request by x-request-id in Gateway > Query.

Am I charged for failed attempts?

You pay for the attempt that served the request. Failed token-endpoint attempts with a known provider cost are charged at that cost, without markup, even if every attempt fails. See Failover.

Can I use my own provider account?

Yes, with a BYOK connection. The provider bills you directly, and those requests don't fail over.

Why isn't a model in /v1/models?

The model may have no published price yet, may not be available in your region, may be blocked by your organization or provider policy, may have no active route, or may require qualification before use. Your key's allowed-models list also hides models. Calling a hidden model returns model_not_found, or 403 with no_eligible_route when a restriction blocks it.

My Anthropic SDK requests return 404.

The Anthropic SDK appends /v1/messages. Set the base URL to gateway-api.mastra.ai, without /v1.

On this page