Projects

Projects are the organizational unit in Gateway. Every project has a unique ID, its own budget, routing policy, and compression settings. Requests are scoped to a project with a project API key, the project_id body field, or the X-Project-Id header. Projects are the foundation: routing, compression, budgeting, and spend tracking all attach to a project.

What you can do with projects

• Set budgets: dollar limit and billing period. Gateway tracks spend and alerts or blocks at thresholds. See Cost governance and savings for details.
• Configure routing: org default or project-specific override. See Routing policies.
• Configure compression: org default or project-specific override. See Context compression.
• Track spend: per-project view in the dashboard, with managed vs BYOK spend and model/provider breakdowns
• Issue project API keys: keys created from the project’s API keys tab attribute every request to the project automatically
• Apply tags: attach key-value tags via headers or API keys to drive tag-based routing rules and spend tracking by tag

Creating a project

Create a project from the Gateway dashboard using the four-step wizard:

1. Details: name, slug (unique per org), and optional description. After creation, the project’s ID (a UUID, used as the project_id value in requests) is shown on the project’s Overview tab.
2. Budget: amount (USD), period (daily, weekly, monthly, quarterly, or yearly), enforcement mode (soft or hard), and alert thresholds. You can skip this step and add a budget later.
3. Routing: use the org default or set a project-specific override, choosing a fallback or intelligent strategy
4. Compression: use the org default or set a project-specific override (disabled, context window only, or cost optimization with a target ratio slider)

Scoping requests to a project

There are three ways to attach a request to a project. Pick the first that fits your setup:

1. Project API key. Create a key from the project’s API keys tab in the dashboard. Every request made with that key attributes to the project automatically, so its routing policy and budget apply with no per-request configuration. This is the right choice for coding agents and IDEs (Claude Code, Codex, Cursor), where you control the key but not the request body.
2. project_id body field. Keep an organization key and pass the project’s ID per request. Supported on /v1/responses and the OpenAI-compatible (/v1/openai) and AI SDK (/v1/ai-sdk) endpoints. Use this when one service talks to several projects with a single key.
3. X-Project-Id header. The same value as an HTTP header. Use it on endpoints without the body field (the Anthropic-compatible /v1/anthropic), or when your client only lets you add headers.

The project’s ID is a UUID, shown on the project’s Overview tab. If a request carries both, the body field wins over the header. A project API key’s project can’t be overridden per request; a conflicting project_id is rejected with 400 project_mismatch.

When a request resolves to a project, Gateway uses that project’s routing policy if one is set; otherwise it falls back to the org default. See Using routing policies for the full resolution order. Without any project reference, requests use org-level defaults and spend is tracked at the org level.

1
from merge_gateway import MergeGateway
2
3
client = MergeGateway(api_key="YOUR_API_KEY")
4
5
response = client.responses.create(
6
    model="openai/gpt-5.2",
7
    input=[
8
        {"type": "message", "role": "system", "content": "You are a helpful programming tutor. Explain the concepts clearly with practical examples."},
9
        {"type": "message", "role": "user", "content": "Explain the concept of recursion in programming with a simple set of examples."},
10
    ],
11
    project_id="4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47",
12
)
13
14
print(response.output[0].content[0].text)

Budgets

Each project can have a budget that caps spend for a billing period: soft limits alert at thresholds (50%, 80%, and 90% by default), hard limits block requests with HTTP 402 once exceeded. Budget changes can take up to an hour to take effect in enforcement, and the dashboard shows color-coded progress per project. See Budgets for how project budgets relate to org caps, per-key limits, and customer budgets.

Tags

Tags are key-value pairs defined at the org level. They serve two purposes:

• Routing: use tags as conditions in tag-based routing rules. For example, route requests tagged customer_tier: enterprise to a quality-first policy. See Routing policies for configuration details.
• Spend tracking: view spend broken down by tag in the dashboard’s “By Tag” tab

The dashboard includes quick-fill templates for common tags like customer_tier, environment, and region.

FAQ

Next steps