> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Quickstart

> Create a virtual key, send one request through the LangWatch AI Gateway with the OpenAI SDK, open the trace and see the spend on the key.

## 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](https://langwatch.ai/docs/ai-gateway/providers/overview.md).
* The `virtualKeys:create` permission in the project. Team Member and Team Admin hold it by default. See [RBAC](https://langwatch.ai/docs/ai-gateway/rbac.md).

## 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](https://mintcdn.com/langwatch/6EHh-4eZyYKZhosJ/images/ai-gateway/vk-create-drawer.png?fit=max\&auto=format\&n=6EHh-4eZyYKZhosJ\&q=85\&s=7b7a4cdd6c40843f6e5a892c18eea31b)

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](https://mintcdn.com/langwatch/6EHh-4eZyYKZhosJ/images/ai-gateway/vk-secret-once.png?fit=max\&auto=format\&n=6EHh-4eZyYKZhosJ\&q=85\&s=ea266fd208bcbe4e65782ba88f2d2aeb)

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-6-luna`. A bare `gpt-6-luna` also works when one of the key's providers serves it.

```bash curl theme={null}
curl https://gateway.langwatch.ai/v1/chat/completions \
  -H "Authorization: Bearer $LANGWATCH_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "messages": [{"role": "user", "content": "Say hi in one word"}]
  }'
```

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.langwatch.ai/v1",
    api_key="vk-lw-...",  # your virtual key
)

response = client.chat.completions.create(
    model="openai/gpt-6-luna",
    messages=[{"role": "user", "content": "Say hi in one word"}],
)
print(response.choices[0].message.content)
```

```typescript TypeScript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.langwatch.ai/v1",
  apiKey: process.env.LANGWATCH_VIRTUAL_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-6-luna",
  messages: [{ role: "user", content: "Say hi in one word" }],
});
console.log(response.choices[0].message.content);
```

The response is a normal OpenAI chat completion. The gateway adds these response headers:

| Header | Value |
| - | - |
| `X-LangWatch-Gateway-Request-Id` | The id of this request. Search it in Trace Explorer or quote it to support. |
| `Traceparent` | The W3C trace context of the span the gateway recorded in your project. Send your own `traceparent` header on the request to nest that span in your trace. |
| `X-LangWatch-Budget-Warning` | Present when a budget on this key is at 80 percent or more, as `scope:percent`. |

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](https://langwatch.ai/docs/ai-gateway/sdks/python.md) and [TypeScript SDK](https://langwatch.ai/docs/ai-gateway/sdks/typescript.md).

## 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:

| Attribute | Meaning |
| - | - |
| `langwatch.virtual_key_id` | The key that served the request. |
| `langwatch.gateway_request_id` | The same id as the `X-LangWatch-Gateway-Request-Id` header. |
| `langwatch.model_provider_id` | The provider credential that served the request. |
| `langwatch.end_user_id` | The end user of your product, when the request carried one. See [Billing and spend events](https://langwatch.ai/docs/ai-gateway/billing-events.md#attribution-what-the-request-carries). |

![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](https://mintcdn.com/langwatch/6EHh-4eZyYKZhosJ/images/ai-gateway/trace-gateway-request.png?fit=max\&auto=format\&n=6EHh-4eZyYKZhosJ\&q=85\&s=7b02bdcd76989beab70c2cf0059ed0bf)

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](https://mintcdn.com/langwatch/6EHh-4eZyYKZhosJ/images/ai-gateway/usage-page.png?fit=max\&auto=format\&n=6EHh-4eZyYKZhosJ\&q=85\&s=64f90b3e73bc6df3a91ae7e7cdbfad50)

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

> [!NOTE]
>
> **Also check:** [Budgets](https://langwatch.ai/docs/ai-gateway/budgets.md) to cap the key, the team or the project, and
> [Virtual keys](https://langwatch.ai/docs/ai-gateway/virtual-keys.md) for scopes, expiry, rotation and the CLI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.