Skip to navigation
Projects and cost

Projects

Group traffic by team, product, or environment, with its own budget, routing, and controls

A project gives one team, product, or environment its own budget, routing policy, compression, guardrails, vendor controls, and spend reporting.

Create a project

In Projects, click Add project and fill in Project details (name, org-unique slug, description), Budget (skippable), and Routing (org default or a project policy). All are editable later:

TabWhat it holds
OverviewThe project ID (a UUID, used as the project_id value), spend, and budget progress
ConfigurationBudget, compression, prompt injection, and DLP overrides
RoutingThe project’s routing policy and Tag rules
ControlsProject-level ZDR, vendor, and region overrides
API keysKeys that attribute every request to this project
SettingsEdit the name, slug, and description, or delete the project. Deleting is blocked while active project API keys exist

Scoping requests to a project

Use a project API key when you control the key but not the body (Claude Code, Cursor), and the header when one service sends several projects’ traffic on one organization key.

MethodWhere it worksProject budget enforced
Project API key, created on the project’s API keys tabEvery endpointYes
X-Project-Id headerEvery endpointYes
project_id body field/v1/responses, /v1/openai, /v1/ai-sdkNo

For a hard limit, use the key or the header (how budgets are enforced).

curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "X-Project-Id: 4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": [
      {"type": "message", "role": "user", "content": "Explain recursion in two sentences."}
    ]
  }'

When methods combine:

  • A project API key locks its project: a header or body value naming another project returns 400 project_mismatch; a match is accepted
  • With an organization key, a body project_id wins over the header for attribution and routing, but the budget check uses the header’s project
  • Combining a project with an Embedded Routing customer returns 400 customer_project_conflict

A project request uses the project’s routing policy, or the org default when it has none.

Tags

For tag-based routing, send tags as key-value pairs in the request’s tags body field. Define each pair for your organization first; GET /v1/tags lists the available pairs. Tag rules on a project’s Routing tab select a different strategy when all pairs in a rule match. Extra request tags don’t prevent a match, and the first matching rule wins.

Deactivating a project

Setting is_active to false through the Projects API doesn’t stop traffic; it drops guardrail overrides and blocks new project API keys. To stop traffic, disable or delete the keys or set a hard limit.

Next steps

Budgets

Cap a project’s spend with soft or hard limits

Routing policies

Give a project its own failover or intelligent routing

Projects API

Create and configure projects from code