Request metadata

Use Cases

Attribute requests to an app or service

Name each request so cost and performance slice by product, feature, or environment.

Group analytics by end user or tenant

Attach an Identity so spend, latency, and error rates attribute to a user, team, or client, with optional per-identity budgets.

Group multi-turn conversations

Tag each turn with a Thread ID so the full conversation groups together in observability.

Slice analytics by business context

Attach key-value metadata, such as tier, channel, or feature flag, and filter traces by those fields.

Overview

Every AI Gateway request can carry context through several mechanisms:

name: marks the app or service
identity: marks the end user or tenant
thread: groups a conversation
metadata: carries business context
tags: adds grouping labels

Each mechanism answers one question and surfaces through its own channel. Use the decision table below to pick the mechanism for a given question. variables also travel with the request, but fill prompt templates instead of describing the request. The how-to for each mechanism lives in App Tracking, Identities, and Thread Management; the span attribute reference is in Metadata.

Which mechanism to use

Mechanism	Answers the question	Use when
`name`	Which app, service, or feature made this call?	Cost and performance per product line, with a fixed set of known surfaces
`identity`	Which end user, team, or client is this request for?	Per-user attribution, tenant billing, per-identity budgets
`thread`	Which conversation or workflow does this request belong to?	Multi-turn chats, multi-step agent workflows, support tickets
`metadata`	What business context applies to this request?	Key-value slicing by tier, channel, region, or feature flag
`tags`	Which labels group these requests?	Grouping across apps, users, or conversations, for example `support`, `premium`, `experiment-a`

Quick Start

Send one request with all five mechanisms attached.

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Refund my order",
    "name": "SupportAssistant-Production",
    "metadata": {
      "customer_tier": "premium",
      "channel": "email"
    },
    "tags": ["support", "refund"],
    "thread": {
      "id": "conversation-abc123",
      "tags": ["user-123"]
    },
    "identity": {
      "id": "user_123"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ORQ_API_KEY,
  baseURL: "https://api.orq.ai/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Refund my order",
  name: "SupportAssistant-Production",
  metadata: { customer_tier: "premium", channel: "email" },
  tags: ["support", "refund"],
  thread: { id: "conversation-abc123", tags: ["user-123"] },
  identity: { id: "user_123" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("ORQ_API_KEY"),
    base_url="https://api.orq.ai/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Refund my order",
    extra_body={
        "name": "SupportAssistant-Production",
        "metadata": {"customer_tier": "premium", "channel": "email"},
        "tags": ["support", "refund"],
        "thread": {"id": "conversation-abc123", "tags": ["user-123"]},
        "identity": {"id": "user_123"},
    },
)

print(response.output_text)

Configuration

Parameter	Type	Required	Description
`name`	string	No	Display name on the trace. Recommended: alphanumeric and hyphens only, under 50 characters, no timestamps or dynamic values.
`metadata`	object	No	Key-value pairs with string values. On the Responses API, non-string values are rejected with a 400.
`tags`	string[]	No	Labels for filtering and reporting.
`thread`	object	No	Groups related requests: `id` (required) plus optional `tags`.
`identity`	object	No	Attributes the request to an end user: `id` (required) plus optional `display_name`, `email`, `metadata`, and `tags`.
`variables`	object	No	Template variables for prompt substitution. Pass secrets as `{"secret": true, "value": "..."}` so they are redacted from traces.

On /v2/router/chat/completions:

metadata is limited to 16 key-value pairs with keys up to 64 characters and values up to 512 characters
thread, identity, and tags are passed under the orq object (orq.thread, orq.identity, orq.tags)
name is passed at the top level

Where each mechanism surfaces

Mechanism	Request field	Span attributes	Traces filter	Reporting API
`name`	`name`	Span name, `gen_ai.operation.name`	Name	Not available
`identity`	`identity`	`orq.identity_id`	Identity	`identity` dimension
`thread`	`thread`	`orq.thread_id`	Thread ID	`thread` entity dimension
`metadata`	`metadata`	`metadata.<key>`	Metadata	Not available
`tags`	`tags`	`orq.tags`	Via span attribute (`orq.tags`)	`tag` entity dimension

Filter names follow the Traces page. Custom metadata surfaces as metadata.<key> span attributes on router requests, and as an orq.metadata JSON attribute on agent and gateway-client spans. See Metadata for the full reference.

Best Practices

Keep app names low-cardinality: Use a small fixed set of app names (around 50 per workspace) with consistent patterns such as Service-Environment. Avoid timestamps or dynamic values, which fragment analytics.
Use a fixed metadata key set: Define a small set of keys (customer_tier, channel, region) and reuse them. High-cardinality keys, such as request IDs or timestamps, defeat filtering and increase storage.
Thread IDs: Use UUIDs or composite keys such as user-{userId}-{sessionId} to avoid collisions across sessions.
Identity IDs: Use predictable patterns such as user-{userId} or tenant-{tenantId} so identities stay consistent across requests.
One mechanism per question: If the value describes the app, use name; if it describes the user, use identity; if it is business context, use metadata.

What not to store in request metadata

PII: Do not put emails, phone numbers, or personal data in metadata, name, or tags; they persist on stored traces. To keep sensitive values out of stored traces, include "metadata" in security.mask, or enable PII Redaction.
Secrets: Pass tokens and keys as template variables with {"secret": true, "value": "..."} so they are redacted from traces. See Run Agents for the variable reference.

Overview

APIs

Routing

Security & Privacy

Model Capabilities

Analytics & Monitoring

Overview

Which mechanism to use

Quick Start

Configuration

Where each mechanism surfaces

Best Practices

What not to store in request metadata

​Overview

​Which mechanism to use

​Quick Start

​Configuration

​Where each mechanism surfaces

​Best Practices

​What not to store in request metadata

Overview

Which mechanism to use

Quick Start

Configuration

Where each mechanism surfaces

Best Practices

What not to store in request metadata