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

# App tracking and analytics for AI requests

> Tag AI Gateway requests with an app name to segment Toqan Router analytics by application, covering cost, latency, errors, and token counts per product or service.

**Use Cases**

* Attributing token costs and latency to specific features or services.
* Monitoring which internal tools or products drive the most LLM usage.
* Filtering observability dashboards by application for debugging or billing.
* Enforcing separate budgets per product line or team.

For the full set of ways to attach context to a request, including identity, threads, and custom metadata, see [Request Metadata](/docs/ai-gateway/request-metadata.md).

App Tracking names each **AI Gateway** request with an application through the `name` parameter, so cost, latency, token counts, and error rates segment by product or service. The name shows on each trace and filters the [**Monitors**](/docs/ai-studio/observability/monitors.md) dashboards by application.

***

## Quick Start

Name your requests to track usage by application or service.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a professional email",
    "name": "EmailAssistant-Production"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Write a professional email",
  name: "EmailAssistant-Production",
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Write a professional email",
    extra_body={"name": "EmailAssistant-Production"},
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Write a professional email" }],
  name: "EmailAssistant-Production",
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Write a professional email"}],
    extra_body={"name": "EmailAssistant-Production"},
)
```

## Configuration

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | The name to display on the trace. If not specified, the default system name will be used. |

> [!NOTE]
>
> For backwards compatibility, `orq.name` is also supported but deprecated. Use top-level `name` for new implementations.

**Default behavior**: If no name provided, system uses default identifier.

## Naming Conventions

### Recommended patterns

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Service-Environment
"UserAPI-Production";
"ChatBot-Development";

// Team-Service-Feature
"Platform-Auth-OAuth";
"ML-Recommendations-v2";

// Application-Version
"MobileApp-v3-1";
"WebPortal-v2-0";
```

### Best practices

* Use consistent patterns across team.
* Include environment (dev/staging/prod).
* Avoid timestamps or dynamic values.
* Keep names under 50 characters.
* Use alphanumeric and hyphens only.

## Use Cases

| Scenario | Naming Strategy | Example |
| - | - | - |
| **Microservices** | Service-based naming | `user-service`, `payment-api` |
| **Multi-tenant** | Tenant identification | `tenant-123`, `enterprise-client` |
| **A/B testing** | Variant tracking | `experiment-A`, `control-group` |
| **Feature flags** | Feature identification | `new-ui-beta`, `legacy-flow` |

## Code examples

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Help me write a professional email to follow up on a job interview",
    "name": "ContentGenerator-BlogPosts"
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Help me write a professional email to follow up on a job interview"
      }
    ],
    "name": "ContentGenerator-BlogPosts"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Help me write a professional email to follow up on a job interview",
  name: "ContentGenerator-BlogPosts",
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Help me write a professional email to follow up on a job interview",
    extra_body={"name": "ContentGenerator-BlogPosts"},
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [
    {
      role: "user",
      content: "Help me write a professional email to follow up on a job interview",
    },
  ],
  name: "ContentGenerator-BlogPosts",
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "user",
            "content": "Help me write a professional email to follow up on a job interview",
        }
    ],
    extra_body={"name": "ContentGenerator-BlogPosts"},
)
```

## Environment Management

### Configuration by environment

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const getTrackingName = (service, environment) => {
  return `${service}-${environment}`;
};

// Usage
const trackingConfig = {
  name: getTrackingName("ChatBot", process.env.NODE_ENV),
  // Results in: "ChatBot-development", "ChatBot-production"
};
```

### Environment-specific examples

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Development
name: "UserAPI-Dev"

// Staging
name: "UserAPI-Staging"

// Production
name: "UserAPI-Prod"
```

## Usage

### Filtering by application

* View requests by specific app/service.
* Compare performance across applications.
* Track costs per application.
* Monitor error rates by service.

### Metrics available

The following metrics are available for App Tracking:

* Request volume per application.
* Response times by service.
* Cost allocation by project.
* Error patterns by environment.

## Advanced Patterns

### Dynamic naming

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const generateTrackingName = (userId, feature) => {
  // For multi-tenant scenarios
  return `tenant-${userId}-${feature}`;
};

// Usage
name: generateTrackingName(user.id, "chat-assistant")
```

### Feature flag integration

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const getFeatureName = (featureFlags) => {
  const activeFeatures = Object.keys(featureFlags)
    .filter((key) => featureFlags[key])
    .join("-");

  return `app-${activeFeatures}`;
};
```

### Version tracking

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Package.json version (replace dots with hyphens)
const packageVersion = require("./package.json").version.replace(/\./g, "-");

name: `MyApp-v${packageVersion}`
```

## Troubleshooting

**Names not appearing in dashboard**

* Check name follows alphanumeric + hyphens pattern.
* Verify requests are being sent successfully.
* Ensure name is under character limit (50 chars).

**Fragmented tracking data**

* Standardize naming conventions across team.
* Use environment variables for consistency.
* Implement a centralized naming function.

**Too many unique names**

* Avoid timestamps or random values.
* Limit to \~50 unique names per account.
* Use hierarchical naming instead of flat structure.

## Monitoring

The following metrics are available for monitoring.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const appMetrics = {
  requestsByApp: {}, // Volume per application
  costsByApp: {}, // Spending per application
  latencyByApp: {}, // Performance per application
  errorsByApp: {}, // Error rates per application
  activeApps: new Set(), // Unique applications
};
```

### Analytics queries

The following queries can be answered using the above metrics.

* Which applications use AI most?
* What's the cost per application?
* Which services have highest error rates?
* How does performance vary by application?

## Best Practices

### Naming standards

* Document naming conventions for your team.
* Use consistent separators (hyphens recommended).
* Include environment in name for clarity.
* Avoid special characters or spaces.

### Example Implementation

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Centralized tracking configuration
class ToqanConfig {
  static getName(service, environment = process.env.NODE_ENV) {
    return `${service}-${environment}`;
  }

  static getConfig(service) {
    return {
      name: this.getName(service),
    };
  }
}

// Usage
const toqanConfig = ToqanConfig.getConfig("ChatBot");
```

To make sure teams within an Engineering Organization align on App Tracking principles:

* Maintain a list of approved application names.
* Use code reviews to enforce naming standards.
* Set up monitoring alerts for new/unexpected names.
* Regular cleanup of unused tracking names.

## Limitations

* **Name constraints**: Alphanumeric characters and hyphens only.
* **Length limits**: Maximum 50 characters per name.
* **Storage impact**: Many unique names increase metadata storage.
* **Query performance**: Large numbers of unique names may slow filtering.
* **No retroactive changes**: Historical traces keep original names.

## Integration Examples

### With external monitoring systems

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const prometheus = {
  histogram: (name: string, value: number, labels: Record<string, string>) => {},
  counter: (name: string, value: number, labels: Record<string, string>) => {},
}; // replace with your Prometheus client, e.g. from prom-client

// Export metrics by application
const exportMetrics = (trackingName: string, responseTime: number, cost: number) => {
  prometheus.histogram("ai_request_duration", responseTime, {
    app: trackingName,
  });
  prometheus.counter("ai_request_cost", cost, { app: trackingName });
};
```

### With logging

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
logger.info("AI request completed", {
  trackingName: "ChatBot-Prod",
  responseTime: 1250,
  model: "gpt-5.6-sol",
  success: true,
});
```


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