Skip to main content

​
What is Request Metadata?

Request Metadata allows you to enhance your API calls with custom data that enables powerful analytics and tracking. By adding metadata to your requests, you can:
  • Track user interactions across sessions
  • Group requests by custom tags
  • Associate requests with specific workflows
  • Add business context to your API usage

​
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",
            "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

​
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",
            "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',
                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.
⌘I