← All guides

How project attribution works

Every request to LunaRoute can carry an optional project ID: a free-form label your client chooses for itself. Use one per app, environment, team, or customer you want to see separately in the usage ledger. A project changes nothing about authentication, routing, concurrency, or price. It only splits reporting.

The Usage & Metrics page in your dashboard ranks the projects you use most and can filter the whole page to one of them.

Sending a project ID

With a key in a header, add one more header:

curl https://gw.lunaroute.com/v1/chat/completions \
  -H "LUNAROUTE-API-KEY: $LUNAROUTE_API_KEY" \
  -H "LUNAROUTE-PROJECT-ID: checkout-agent" \
  -H "content-type: application/json" \
  -d '{"model": "glm-5.3", "messages": [{"role": "user", "content": "hello"}]}'

With the key in the path (/a/{key}/...), put p/{project} after the key:

https://gw.lunaroute.com/a/{key}/p/checkout-agent/v1/chat/completions

A request carries a project one way or the other. Sending both a LUNAROUTE-PROJECT-ID header and a /p/{project} segment is rejected with 400 AMBIGUOUS_PROJECT_ID. Prefer the header: the /a/ surfaces are the legacy form, and their responses are marked deprecated.

The 128-byte limit

A project ID is at most 128 UTF-8 bytes, which is not the same as 128 characters: 128 ASCII characters fit, while an accented or CJK character costs two or more bytes each. There is no charset rule and no registry, so any printable string inside the byte budget is a valid label. A longer one is refused with 400 PROJECT_ID_TOO_LONG on the HTTP routes that record a project; the MCP endpoint answers a JSON-RPC invalid_request tool error instead.

The same limit guards both ends: the gateway rejects an over-long ID as the request arrives on the routes that record it, and the metrics filter refuses one too, rather than quietly returning an empty page.

Values are stored and compared exactly as you sent them. Nothing is trimmed, case-folded, or normalized, so web and Web are two different projects, and the string you filter on has to match the stored one byte for byte.

Reading it in Usage & Metrics

Open Usage & Metrics for your organization. Top Projects lists up to ten projects for the selected range — or for the longest window it can rank in one pass, which the card names when that window is shorter — ranked by requests or by token total, whichever sort the page is on, with both counts for each. When even the shortest supported 15-minute window is over its per-org budget, the card is omitted entirely rather than scanned unbounded. Pick a row and the whole page is scoped to that project, with the pick kept in the URL as ?project=<id>, so a reload or a shared link restores it. The chip beside the range selector shows the active project and clears it.

IDs are listed and filtered verbatim: nothing is shortened, prettified, or matched loosely. What you sent is what appears in the ranking, in the chip, and in the URL.

What a filtered view leaves out

Attribution is best effort, so a project-filtered view counts only the rows that carry a project ID. Org-wide totals still include everything, which means a project total is a floor rather than the whole truth about that project's work.

  • Requests without a project ID. A client that sends no project belongs to no project. Its usage is in the org-wide numbers and in every other breakdown, never in a project-filtered view.
  • Traffic from surfaces that used to drop the header. The MCP endpoint, the image tools (including POST /v1/images/uploads) and audio transcription, POST /v1/systemone, and the bare /a/{key} path-auth routes (/a/{key}/v1/chat/completions, /a/{key}/v1/completions, /a/{key}/v1/messages and /a/{key}/v1/responses, with its /responses alias) only started recording a project in November 2026. Usage that reached them before then kept no project, even where the client sent one.

So if a project's number looks lower than you expect, check which of these your client falls under before you go looking for missing capacity.

Keep secrets out of project IDs

A project ID is a label, not a secret store, and it travels further than you might expect:

  • It rides shareable URLs. Picking a project writes it into ?project=, so anyone you send the link to receives the ID.
  • It lands in request logs. The /p/{project} form puts the ID in the request URL, which request logs record, and the value is stored with usage events that dashboards, exports, and support work all read.

Keep a project ID to something you would be comfortable pasting into a ticket — checkout-agent, staging, team-platform. Never put an API key, a customer's name or email, or any other secret or personal data in one.

Get started