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 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)

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.

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="my-project-id",
12
)
13
14
print(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:

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%+).

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