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:

View request logs in the Requesty Console.

• 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

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

Reply in {{ language }} for {{ audience }}.

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

{
  "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:

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

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

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();

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