Skip to main content

Before you start

You need:
  • A LangWatch account with a project.
  • One provider credential under Settings > Model Providers, for example your OpenAI API key. The gateway uses the credentials already configured there. See Providers.
  • The virtualKeys:create permission in the project. Team Member and Team Admin hold it by default. See RBAC.

1. Create a virtual key

  1. Open AI Gateway > Virtual Keys and click New virtual key.
  2. Enter a name, for example acme-support-agent.
  3. Keep Ownership on Project. Traces and costs of this key land in the selected project.
  4. Optionally set a Budget, for example $50 per month. The key is blocked at the limit.
  5. Keep Provider access on All providers, or select the providers this key may reach.
  6. Click Create.
The New virtual key drawer filled in for acme-support-agent with Project ownership, a 50 dollar monthly budget and all providers selected

The New virtual key drawer: name, ownership on the project, a $50 monthly budget with the inherited organization budget below it, and provider access.

The secret is shown once. Copy it and store it in your secret manager. LangWatch stores a hash, and the list shows only the prefix, for example vk-lw-01HZX9N.
The Save your virtual key secret dialog with the masked secret and a Python usage example

The secret dialog, shown once, with a copy button and a usage example for the OpenAI SDK.

2. Send a request

Point the OpenAI SDK at the gateway and use the virtual key as the API key. Name the model as provider/model, for example openai/gpt-5-mini. A bare gpt-5-mini also works when one of the key’s providers serves it.
The response is a normal OpenAI chat completion. The gateway adds these response headers: For the Anthropic SDK, set base_url="https://gateway.langwatch.ai" and the virtual key as api_key. The SDK sends the key in the X-Api-Key header, which the gateway accepts. See Python SDK and TypeScript SDK.

3. Open the trace

Open Trace Explorer in the project you selected under Ownership. The request appears as a gen_ai.chat span with the model, the tokens, the cost and these attributes:
Trace Explorer with a gen_ai.chat span open, showing cost, tokens, the model and the langwatch.virtual_key_id, gateway_request_id and model_provider_id attributes

One gateway request in Trace Explorer: duration, cost, tokens and model in the header, the gateway attributes under Metadata.

4. See the spend

Open AI Gateway > Usage for total spend, requests, cost per request, top virtual keys and top models over the selected period. The Virtual Keys list shows a Spent this month column per key, and clicking it opens Usage filtered to that key.
The Usage page with total spend, requests, average cost per request, blocked by guardrail, and the top keys and models tables

AI Gateway > Usage over the last 30 days: the four tiles, the top virtual keys and the top models.

Also check: Budgets to cap the key, the team or the project, and Virtual keys for scopes, expiry, rotation and the CLI.
Last modified on September 6, 2026