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.