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

# Request Metadata

> Add custom metadata to your API calls for powerful analytics

## What is Request Metadata?

Request Metadata allows you to enhance your API calls with custom data that enables powerful analytics, tracking, and prompt template rendering. By adding metadata to your requests, you can:

<Note>
  **[View request logs](https://app.requesty.ai/logs)** in the Requesty Console.
</Note>

* Track user interactions across sessions
* Group requests by custom tags
* Associate requests with specific workflows
* Add business context to your API usage
* Apply prompt templates per request, pass template variables, and inherit saved prompt settings

## How It Works

1. Use the standard OpenAI client with Requesty's base URL
2. Add the `extra_body` parameter with your metadata
3. View and analyze this data in your Requesty dashboard

```python theme={"dark"}
requesty_api_key = "YOUR_REQUESTY_API_KEY"  # Safely load your API key

client = openai.OpenAI(
    api_key=requesty_api_key,
    base_url="https://router.requesty.ai/v1"
)

# Add metadata via the extra_body parameter
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Your prompt here"}],
    extra_body={
        "requesty": {
            "tags": ["workflow-a", "product-page"],
            "user_id": "user_1234",
            "trace_id": "session_abc123",
            "prompt_id": "localized_product_writer:2",
            "prompt_variables": {
                "language": "English",
                "audience": "enterprise buyers"
            },
            "extra": {
                "country": "canada",
                "prompt_title": "product description generator",
                "tier": "premium"
            }
        }
    }
)
```

## Key Metadata Fields

### Core Fields

* **tags**: Array of strings for grouping related requests
* **user\_id**: Identifier for the end user making the request
* **trace\_id**: Unique identifier to track related requests in a workflow

### Extra Context

The `extra` object can include any custom fields relevant to your business:

* **country**: User's location for geographic analysis
* **prompt\_title**: Descriptive name of the prompt's purpose
* **tier**: User's subscription level
* **language**: Preferred language of the user
* **application**: Source application or feature

### Prompt Templates

Use `prompt_id` to apply a [Prompt Template](/features/prompt-library) for a single request, and `prompt_variables` to pass per-request values into the template. These values are used while Requesty renders the prompt template and are not sent to the model as a separate field.

If the selected prompt has model parameters or a response format configured, Requesty applies those settings after rendering the template. Prompt-level settings override the matching request fields, including `temperature`, `max_tokens`, `reasoning_effort`, and `response_format`.

| Field              | Description                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt_id`        | Prompt template name, optionally with a version: `"name"` uses the latest version, `"name:version"` pins a specific one (e.g. `"localized_product_writer:2"`) |
| `prompt_variables` | Key-value pairs substituted into the template's `{{ variable }}` placeholders                                                                                 |

For example, if a prompt template named `localized_product_writer` contains:

```text theme={"dark"}
Reply in {{ language }} for {{ audience }}.
```

Apply that template and pass variables in the Requesty extras object:

```json theme={"dark"}
{
  "requesty": {
    "prompt_id": "localized_product_writer:2",
    "prompt_variables": {
      "language": "French",
      "audience": "enterprise buyers"
    }
  }
}
```

Requesty renders the prompt template before routing the request, so the model sees the rendered instruction:

```text theme={"dark"}
Reply in French for enterprise buyers.
```

## Benefits

* **User Journey Analysis**: Track how users interact with AI across sessions
* **Cost Attribution**: Assign AI usage costs to specific business units
* **Performance Optimization**: Identify which prompts perform best for specific uses
* **Workflow Visualization**: See how multiple API calls connect in complex processes

## Implementation Examples

### Python Example

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

requesty_api_key = "YOUR_REQUESTY_API_KEY"  # Safely load your API key

# Initialize client
client = openai.OpenAI(
    api_key=requesty_api_key,
    base_url="https://router.requesty.ai/v1"
)

# Make request with metadata
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Generate a product description for a coffee maker"}],
    extra_body={
        "requesty": {
            "tags": ["product-content", "e-commerce"],
            "user_id": "merchant_5678",
            "trace_id": "workflow_product_launch_123",
            "prompt_id": "localized_product_writer:2",
            "prompt_variables": {
                "language": "English",
                "audience": "online shoppers"
            },
            "extra": {
                "country": "usa",
                "prompt_title": "product description",
                "department": "marketing",
                "product_category": "kitchen_appliances"
            }
        }
    }
)

print(response.choices[0].message.content)
```

### Node.js Example

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

// Load environment variables
dotenv.config();
const REQUESTY_API_KEY = process.env.REQUESTY_API_KEY;

// Initialize OpenAI client
const openai = new OpenAI({
    apiKey: REQUESTY_API_KEY,
    baseURL: 'https://router.requesty.ai/v1',
});

async function generateWithMetadata() {
    try {
        const response = await openai.chat.completions.create({
            model: 'openai/gpt-4o',
            messages: [{ role: 'user', content: 'Write a blog intro about AI productivity tools' }],
            requesty: {
                tags: ['content-creation', 'blog'],
                user_id: 'editor_9012',
                trace_id: 'article_draft_456',
                prompt_id: 'blog_intro_writer:1',
                prompt_variables: {
                    language: 'English',
                    audience: 'technical readers',
                },
                extra: {
                    country: 'uk',
                    prompt_title: 'blog intro',
                    content_type: 'educational',
                    target_audience: 'technical',
                },
            },
        });

        console.log(response.choices[0].message.content);
    } catch (error) {
        console.error('Error:', error);
    }
}

generateWithMetadata();
```

<Tip>For consistent analytics, establish naming conventions for your tags and metadata fields across your organization.</Tip>