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

# Analytics Headers

> Tag every request with custom HTTP headers for powerful per-agent, per-branch, and per-team analytics

## What are Analytics Headers?

Requesty supports two kinds of analytics headers:

<Note>
  **[Configure analytics headers](https://app.requesty.ai/analytics)** in the Requesty Console.
</Note>

1. **Origin headers**. `HTTP-Referer` and `X-Title` identify *which app or tool* is making the request. Set them once and every request is automatically tagged.
2. **Custom analytics headers**. `X-Requesty-*` headers let you attach arbitrary metadata (agent name, branch, team, environment, etc.) to requests.

Both types are captured by Requesty, stripped before forwarding to the AI provider, and made available as **dimensions** in your [analytics dashboards](https://app.requesty.ai/analytics). They are the simplest way to add metadata, no SDK changes, no request body modifications. Just set an HTTP header.

```bash theme={"dark"}
curl https://router.requesty.ai/v1/chat/completions \
  -H "Authorization: Bearer $REQUESTY_API_KEY" \
  -H "HTTP-Referer: https://yourapp.com" \
  -H "X-Title: My App" \
  -H "X-Requesty-Agent: my-support-bot" \
  -H "X-Requesty-Environment: production" \
  -H "X-Requesty-Team: platform" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

## Origin Headers. `HTTP-Referer` & `X-Title`

Requesty recognizes two **standard origin headers** that identify where a request comes from:

| Header         | Stored as        | Purpose                                            |
| -------------- | ---------------- | -------------------------------------------------- |
| `HTTP-Referer` | `origin_referer` | Your site or app URL (e.g., `https://yourapp.com`) |
| `X-Title`      | `origin_title`   | A human-readable app name (e.g., `My App`)         |

These headers are **optional but recommended**. Add them once via `default_headers` and every request is tagged automatically. Many integrations set them for you, for example, [Cline](https://cline.bot), [Roo Code](https://github.com/RooVetGit/Roo-Cline), [Claude Code](/integrations/claude-code), and [Open WebUI](/integrations/openwebui) all send their own `HTTP-Referer` and `X-Title` values so you can filter traffic by tool in your dashboards.

<CodeGroup>
  ```python Python theme={"dark"}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_REQUESTY_API_KEY",
      base_url="https://router.requesty.ai/v1",
      default_headers={
          "HTTP-Referer": "https://yourapp.com",
          "X-Title": "My App",
      },
  )
  ```

  ```javascript Node.js theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "YOUR_REQUESTY_API_KEY",
    baseURL: "https://router.requesty.ai/v1",
    defaultHeaders: {
      "HTTP-Referer": "https://yourapp.com",
      "X-Title": "My App",
    },
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://router.requesty.ai/v1/chat/completions \
    -H "Authorization: Bearer $REQUESTY_API_KEY" \
    -H "HTTP-Referer: https://yourapp.com" \
    -H "X-Title: My App" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-sonnet-4-5",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```
</CodeGroup>

In analytics, filter or **Group By** `origin_title` to break down usage by app, or by `origin_referer` to see traffic by URL.

## Custom Analytics Headers. `X-Requesty-*`

## How It Works

1. Add one or more `X-Requesty-*` headers to your request.
2. Requesty extracts the headers and **removes them** before forwarding to the AI provider, no data leaks upstream.
3. The header values are stored as custom metadata fields on the request.
4. In analytics, filter or **Group By** those fields to slice your data any way you want.

<Info>
  Header matching is **case-insensitive**. `x-requesty-team`, `X-REQUESTY-TEAM`, and `X-Requesty-Team` are all treated the same.
</Info>

## Naming Your Headers

Any header matching the `X-Requesty-<Name>` pattern is captured. The `<Name>` part (after the prefix) becomes the field key in analytics.

| Header                   | Analytics field |
| ------------------------ | --------------- |
| `X-Requesty-Agent`       | `Agent`         |
| `X-Requesty-Branch`      | `Branch`        |
| `X-Requesty-Environment` | `Environment`   |
| `X-Requesty-Team`        | `Team`          |
| `X-Requesty-Customer`    | `Customer`      |

You can use any name you like, there is no fixed list. Pick names that match the dimensions you care about.

## Use Cases

### Name your AI agent

Give each agent or bot a distinct identity so you can track cost and usage per agent:

```bash theme={"dark"}
-H "X-Requesty-Agent: support-bot"
-H "X-Requesty-Agent: code-reviewer"
-H "X-Requesty-Agent: data-pipeline"
```

Then in the **Advanced** analytics tab, **Group By** → `Agent` to see a cost and request breakdown per agent.

### Track by environment

Separate production traffic from development and staging:

```bash theme={"dark"}
-H "X-Requesty-Environment: production"
```

### Track by team or department

Attribute AI costs to the team that generated them:

```bash theme={"dark"}
-H "X-Requesty-Team: backend"
-H "X-Requesty-Department: engineering"
```

### Track by customer

If you're building AI features for multiple customers, tag each request:

```bash theme={"dark"}
-H "X-Requesty-Customer: acme-corp"
```

### Track git context

Tag requests with the branch and repo to see which feature branches are driving cost:

```bash theme={"dark"}
-H "X-Requesty-Branch: feat/new-onboarding"
-H "X-Requesty-Repo: myorg/backend"
```

<Tip>
  The [Claude Code analytics wrapper](/integrations/claude-code#claude-code-analytics) does this automatically, it tags every request with your current git branch, repo, agent version, and OS username.
</Tip>

## Implementation Examples

### Python (OpenAI SDK)

```python theme={"dark"}
import openai

client = openai.OpenAI(
    api_key="YOUR_REQUESTY_API_KEY",
    base_url="https://router.requesty.ai/v1",
    default_headers={
        "X-Requesty-Agent": "my-support-bot",
        "X-Requesty-Environment": "production",
    }
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Hello"}]
)
```

### Node.js (OpenAI SDK)

```javascript theme={"dark"}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_REQUESTY_API_KEY",
  baseURL: "https://router.requesty.ai/v1",
  defaultHeaders: {
    "X-Requesty-Agent": "my-support-bot",
    "X-Requesty-Environment": "production",
  },
});

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4-5",
  messages: [{ role: "user", content: "Hello" }],
});
```

### cURL

```bash theme={"dark"}
curl https://router.requesty.ai/v1/chat/completions \
  -H "Authorization: Bearer $REQUESTY_API_KEY" \
  -H "X-Requesty-Agent: my-support-bot" \
  -H "X-Requesty-Environment: production" \
  -H "X-Requesty-Team: backend" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "messages": [{"role": "user", "content": "Summarize this document"}]
  }'
```

### Claude Code (automatic)

Install the Requesty analytics wrapper and every Claude Code session automatically sends:

| Header                | Value                      |
| --------------------- | -------------------------- |
| `X-Requesty-Branch`   | Current git branch         |
| `X-Requesty-Repo`     | `org/repo` from git origin |
| `X-Requesty-Ai-Agent` | Claude Code version        |
| `X-Requesty-User`     | OS username                |

```bash theme={"dark"}
curl -fsSL https://www.requesty.ai/claude/install.sh | bash
```

See [Claude Code Analytics](/integrations/claude-code#claude-code-analytics) for details.

## Viewing in Dashboards

Once you start sending analytics headers, the fields appear in the [Analytics dashboard](https://app.requesty.ai/analytics):

1. Open the **Advanced** tab.
2. In the **Group By** dropdown, select your custom field (e.g., `Agent`, `Environment`, `Team`).
3. Choose a **Metric** (Cost, Requests, Tokens, Latency, etc.) and a **Time Range**.
4. Optionally add **Filters** to narrow down (e.g., `Agent` = `support-bot`).

You can combine analytics headers with any other grouping or filter, for example, group by `Agent` and filter by `model` = `anthropic/*` to see which agents use Anthropic models the most.

<Tip>
  Establish naming conventions for your analytics headers across your organization. Consistent names like `X-Requesty-Team`, `X-Requesty-Environment`, and `X-Requesty-Agent` make dashboards easy to read for everyone.
</Tip>

## Analytics Headers vs. Request Metadata

Requesty supports three ways to attach metadata:

|                                     | Origin Headers                              | Custom Analytics Headers                               | [Request Metadata](/features/request-metadata)                            |
| ----------------------------------- | ------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
| **Headers**                         | `HTTP-Referer`, `X-Title`                   | `X-Requesty-*`                                         | `requesty` field in the request body                                      |
| **Best for**                        | Identifying the app or tool making requests | Infrastructure-level tags (agent, branch, environment) | Application-level context (user ID, trace ID, tags) that vary per request |
| **SDK changes**                     | None, set `default_headers` once            | None, set `default_headers` once                       | Requires `extra_body` or body modification per request                    |
| **Supports arrays**                 | No                                          | No, single string values only                          | Yes. `tags` is an array                                                   |
| **Supports `user_id` / `trace_id`** | No                                          | No, use Request Metadata for these                     | Yes                                                                       |

All three methods can be used together. For example, set `HTTP-Referer` and `X-Title` to identify your app, `X-Requesty-Agent` and `X-Requesty-Environment` for infrastructure tags, and add per-request `user_id` and `tags` via the request body.

## Privacy & Security

* Analytics headers are **stripped** from the request before it is forwarded to the AI provider. The provider never sees them.
* Header values are stored as metadata alongside the request log in your Requesty organization, visible only to your team.
* Do not put sensitive data (passwords, tokens, PII) in analytics headers.

## Related

* [Request Metadata](/features/request-metadata). Body-based metadata with `user_id`, `trace_id`, and `tags`
* [Usage Analytics](/features/usage-analytics). Dashboard overview and filtering
* [Cost Tracking](/features/cost-tracking). Cost breakdowns by any dimension
* [Claude Code Analytics](/integrations/claude-code#claude-code-analytics). Automatic header tagging for Claude Code