Fresh 2026

Projects

Project creation, budget enforcement, routing and compression overrides, tags, and request scoping via project_id.

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 via the project_id body field. 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
• 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, ID (unique per org, used as the project_id value), and optional description
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)

All settings are editable after creation. Projects can be deactivated without deleting.

---

Scoping requests to a project

Pass the project_id field in the request body with the project's ID. Without it, requests use org-level defaults.

When a request includes project_id, Gateway uses that project's routing policy if one is set; otherwise it falls back to the org default. See Routing policies for the full resolution order.

from merge_gateway import MergeGateway

client = MergeGateway(api_key="YOUR_API_KEY")

response = client.responses.create(
    model="openai/gpt-5.2",
    input=[
        {"type": "message", "role": "system", "content": "You are a helpful programming tutor. Explain the concepts clearly with practical examples."},
        {"type": "message", "role": "user", "content": "Explain the concept of recursion in programming with a simple set of examples."},
    ],
    project_id="my-project-id",
)

print(response.output[0].content[0].text)

import { MergeGateway } from "merge-gateway-sdk";

const client = new MergeGateway({ apiKey: "YOUR_API_KEY" });

const response = await client.responses.create({
  model: "openai/gpt-5.2",
  input: [
    { type: "message", role: "system", content: "You are a helpful programming tutor. Explain the concepts clearly with practical examples." },
    { type: "message", role: "user", content: "Explain the concept of recursion in programming with a simple set of examples." },
  ],
  project_id: "my-project-id",
});

console.log(response.output[0].content[0].text);

---

Budgets

Each project can have a budget that caps spend for a billing period. How Gateway enforces that cap depends on the enforcement mode:

Enforcement Mode	Behavior	Use Case
Soft Limit	Alerts at thresholds; requests continue	Visibility without disruption
Hard Limit	Blocks requests (HTTP 402) once exceeded	Strict cost control

Alert thresholds default to 50%, 80%, and 90% of the budget. The dashboard shows color-coded progress bars: blue (< 80%), yellow (80-100%), red (100%+).

For complete coverage of budgets, billing, and cost-saving strategies, see Cost governance and savings

---

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

Yes. Separate projects by environment, team, or product feature to get independent budgets, routing, and spend tracking for each.

Requests use org-level defaults for routing and compression. Spend is tracked at the org level and not attributed to any project.

No. The ID is used in API requests and spend tracking and cannot be changed. All other settings are editable.

Yes. Deactivating a project stops it from accepting requests but retains its configuration and history.

Projects define static configuration: budget, routing policy, and compression settings. Tags are dynamic per-request metadata used for routing decisions and spend tracking within a project.

---

Next steps

Control AI spend with budgets, unified billing, and automatic cost optimization

Configure intelligent routing, failover, and cost optimization across providers

Automatically reduce token usage and avoid context window limits