Skip to main content

​
Overview

Visca AI Gateway allows you to attach custom metadata to every API request, enabling detailed tracking, analytics, and debugging across your entire AI infrastructure.

Request Tracking

Track requests with custom identifiers and user information

Cost Attribution

Attribute costs to specific users, teams, or projects

Usage Analytics

Analyze usage patterns by any custom dimension

Debugging

Debug issues with detailed request context

​
Adding Metadata

Attach metadata to any request using the metadata field: 
import openai

client = openai.OpenAI(
base_url="https://gateway.visca.ai/v1",
api_key="your-api-key"
)

response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}],
extra_body={
"metadata": {
"user_id": "user-123",
"session_id": "sess-456",
"environment": "production",
"feature": "chat-assistant",
"version": "2.1.0"
}
}
)

​
Metadata Fields

​
user_id
string
Identifier for the end user making the request
​
session_id
string
Session or conversation identifier
​
environment
string
Environment (production, staging, development, etc.)
​
feature
string
Feature or product area generating the request
​
version
string
Application or API version
​
organization_id
string
Organization or tenant identifier for multi-tenant apps
​
team_id
string
Team or department identifier
​
custom_fields
object
Any additional custom fields specific to your use case

​
Querying by Metadata

Retrieve analytics filtered by metadata: 
curl https://gateway.visca.ai/v1/analytics/requests?user_id=user-123 \
  -H "Authorization: Bearer your-api-key"

​
Use Cases

  • Multi-Tenant SaaS
  • A/B Testing
  • Internal Tools
  • Customer Support
{
  "metadata": {
    "organization_id": "org-123",
    "user_id": "user-456",
    "plan": "enterprise",
    "region": "us-east-1"
  }
}
Track costs per organization and enforce usage limits by plan tier.

​
Analytics Dashboard

View real-time analytics filtered by metadata in the dashboard:
1

Navigate to Analytics

Go to the Analytics section in your dashboard
2

Select Metadata Dimension

Choose which metadata field to filter or group by
3

Apply Filters

Add multiple filters to drill down into specific segments
4

Export Data

Export filtered data as CSV or JSON for further analysis

​
Best Practices

  • Use snake_case for field names - Keep field names short but descriptive - Document your metadata schema for your team - Avoid spaces and special characters in field names
  • Include essential tracking information only - Avoid deeply nested objects
  • Keep metadata payload under 1KB - Don’t include sensitive information (passwords, tokens, PII)
  • Use hierarchical identifiers (org_id → team_id → user_id) - Include timestamps if tracking sessions - Add version numbers to track changes over time - Use standardized values for categorical fields
  • Never include API keys or secrets in metadata - Hash or encrypt sensitive identifiers if necessary - Follow GDPR/privacy regulations for user data - Use organization IDs instead of user names

​
Metadata Retention

Metadata is retained for 90 days on all plans. Enterprise plans can configure custom retention periods up to 2 years.

​
Limits

​
Max fields per request
number
default:"50"
Maximum number of metadata fields per request
​
Max field name length
number
default:"64"
Maximum length of metadata field names
​
Max field value length
number
default:"256"
Maximum length of metadata field values
​
Max total size
string
default:"1KB"
Maximum total size of metadata payload

​
Next Steps

Analytics API

Query and export analytics data programmatically

Usage Dashboard

Visualize usage patterns and costs

Cost Attribution

Set up cost centers and chargebacks

Rate Limiting

Enforce usage limits by metadata