> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Orq span attributes reference
> Complete reference for orq.* OpenTelemetry span attributes emitted by the AI Gateway across traces, webhook payloads, and trace exports.
`orq.*` attributes are OpenTelemetry span attributes emitted by the **AI Gateway** on every trace span. They appear in the [**Traces**](/docs/ai-gateway/traces) panel, in [LLM webhook](/docs/ai-studio/organization/webhooks) payloads, and in trace exports. Core attributes appear on every span; attributes in **Invoked resources**, **Guardrails**, and **Routing** sections appear only when the relevant feature was active.
## Quick reference
| What to find | Attributes |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Span type](#span-type) | `orq.span_type` |
| [Model](#model) | `orq.model.id`, `orq.model.provider`, `orq.model.type`, `orq.model.is_private` |
| [Cost](#cost-and-billing) | `orq.billing.*` |
| [Tenant scope](#tenant-scope) | `orq.organization_id`, `orq.workspace_id`, `orq.project_id`, `orq.identity_id`, `orq.api_key_id`, `orq.product` |
| [Invoked resources](#invoked-resources) | `orq.deployment_id`, `orq.deployment_key`, `orq.deployment.variant_id`, `orq.prompt_id`, `orq.knowledge_id`, `orq.memory_store_id`, `orq.playground_id`, `orq.dataset_id`, `orq.schedule_id`, `orq.workflow.run_id` |
| [Conversation](#conversation-and-session-grouping) | `orq.thread_id`, `orq.session_id`, `orq.agent_execution_id` |
| [Custom metadata](#custom-metadata-and-attribution) | `orq.metadata`, `orq.tags`, `orq.variables`, `orq.object_name` |
| [Guardrail rules and routing rules](#guardrail-rules-and-routing-rules) | `orq.routing_rule.id`, `orq.guardrail_rule.ids`, `orq.guardrail.*` |
| [Guardrails](#guardrails) | `orq.evaluator.id`, `orq.evaluator.type`, `orq.evaluator.version`, `orq.evaluator.output_type`, `orq.evaluation.stage` |
| [Routing and fallback](#routing-fallback-and-model-selection) | `orq.fallback.*`, `orq.auto_router.*`, `orq.load_balancer.*` |
| [Framework source](#framework-source) | `orq.trace.framework.name` |
## Span type
Classifies the kind of work a span represents. Use `orq.span_type` to filter spans by operation type in the [**Traces**](/docs/ai-gateway/traces) panel or [LLM webhook](/docs/ai-studio/organization/webhooks) payloads.
| Attribute | Description |
| --------------- | ------------------- |
| `orq.span_type` | Span operation type |
Common values:
| Value | Meaning |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `span.chat_completion` | Chat completion routed through the [**AI Gateway**](/docs/ai-gateway/using-the-router) |
| `span.responses` | [Responses API](/docs/ai-studio/ai-engineering/run-agents) call |
| `span.embedding` | Embeddings |
| `span.retrieval` | Knowledge retrieval |
| `span.evaluator` | Evaluator or guardrail |
| `span.agent` | Agent step within a run |
| `span.agent_execution` | Full agent run |
| `span.tool` | Tool execution |
| `span.fallback_selected` | Fallback model selected |
| `span.auto_router` | Auto-router decision |
| `span.load_balancer` | Load balancer decision |
## Model
| Attribute | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `orq.model.id` | **Orq.ai** model catalog ID (UUID). For the human-readable model name, see `gen_ai.response.model` below. |
| `orq.model.provider` | Provider, e.g. `"openai"`, `"anthropic"` |
| `orq.model.type` | Model type, e.g. `"chat"`, `"embedding"` |
| `orq.model.is_private` | Whether a workspace-private model was used (a model added to the workspace model catalog, not a shared **Orq.ai** model) |
Related standard fields:
* `gen_ai.request.model`: model requested by the caller
* `gen_ai.response.model`: model that actually ran; use this for the human-readable model name, as it reflects the true model after any routing or fallback
## Cost and billing
These attributes appear in the **Economics** panel, trace list, and LLM webhook payloads.
| Attribute | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `orq.billing.total_cost` | Total cost for the span (float, USD) |
| `orq.billing.input_cost` | Input token cost (float, USD) |
| `orq.billing.output_cost` | Output token cost (float, USD) |
| `orq.billing.cache_read_cost` | Prompt cache read cost (float, USD) |
| `orq.billing.cache_write_cost` | Prompt cache write cost (float, USD) |
| `orq.billing.reasoning_cost` | Reasoning token cost (float, USD) |
| `orq.billing.audio_input_cost` | Audio input cost (float, USD) |
| `orq.billing.audio_output_cost` | Audio output cost (float, USD) |
| `orq.billing.web_search_cost` | Web search fees (float, USD) |
| `orq.billing.billable` | Whether this span counts toward workspace usage billing (bool). `false` for cached responses and internal evaluator calls. |
| `orq.billing.pricing_tier` | Pricing tier: `"standard"`, `"extended_128k"`, `"extended_200k"` (string) |
| `orq.billing.threshold_exceeded` | A configured budget threshold was exceeded (bool). The call still completes; this flag signals that alerting or enforcement rules may apply. |
| `orq.billing.integration_id` | ID of the provider integration (the API key configuration for a specific provider account) used to look up pricing rates (string) |
Token counts live under `gen_ai.usage.*`, not `orq.*`.
## Tenant scope
Scope a trace to the organization, workspace, and product surface.
| Attribute | Description |
| --------------------- | ---------------------------------------------------------------- |
| `orq.organization_id` | Organization the call belongs to |
| `orq.workspace_id` | Workspace |
| `orq.project_id` | Project within the workspace |
| `orq.identity_id` | End-user [**Identity**](/docs/ai-gateway/identities) (preferred) |
| `orq.contact_id` | Legacy alias for identity; same meaning as `orq.identity_id` |
| `orq.api_key_id` | API key used for the request |
| `orq.product` | Product surface, e.g. `"router"`, `"agents"`, `"spreadsheets"` |
Filter traces by project, or assign cost to an [**Identity**](/docs/ai-gateway/identities).
## Invoked resources
Links a trace to the **Orq.ai** resources that served the request.
| Attribute | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| `orq.deployment_id` | [**Deployment**](/docs/ai-studio/ai-engineering/deployments) ID |
| `orq.deployment_key` | Deployment key/slug |
| `orq.deployment.variant_id` | Variant that served the request |
| `orq.prompt_id` | [**Prompt**](/docs/ai-studio/prompts/prompts) resource |
| `orq.knowledge_id` | [Knowledge base](/docs/ai-studio/ai-engineering/knowledge-bases-memory-stores) used in retrieval |
| `orq.memory_store_id` | Memory store ID, present on spans that use memory-augmented retrieval |
| `orq.playground_id` | Playground session ID, present on spans initiated from the Playground |
| `orq.dataset_id` | Dataset ID, present on spans triggered by evals or experiments |
| `orq.schedule_id` | Schedule ID, present on spans triggered by a [schedule](/docs/ai-studio/ai-engineering/run-agents) |
| `orq.workflow.run_id` | Workflow run |
Use these to answer: which [deployment](/docs/ai-studio/ai-engineering/deployments), [prompt](/docs/ai-studio/prompts/prompts), [knowledge base](/docs/ai-studio/ai-engineering/knowledge-bases-memory-stores), [schedule](/docs/ai-studio/ai-engineering/run-agents), or workflow produced this trace? To identify which agent execution produced this trace, use `orq.agent_execution_id`.
## Conversation and session grouping
| Attribute | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `orq.thread_id` | [**Thread**](/docs/ai-gateway/thread-management) ID: groups turns within a single conversation |
| `orq.session_id` | Session ID: groups across multiple threads or conversations |
| `orq.agent_execution_id` | A single [**Agent**](/docs/ai-studio/ai-engineering/run-agents) run |
`orq.thread_id` groups individual turns into a conversation; `orq.session_id` groups across conversations for broader session tracking. Pass `orq.thread_id` to group related requests into a [conversation thread](/docs/ai-gateway/thread-management).
The standard OTel field `gen_ai.conversation.id` is also supported. When both are present, `orq.thread_id` takes precedence as the first-class thread identifier in the UI and trace exports.
## Custom metadata and attribution
| Attribute | Description |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `orq.metadata` | Custom key-value metadata (JSON string on the span) |
| `orq.tags` | Request-level tags for filtering and reporting |
| `orq.variables` | Template variables passed by the caller to fill prompt placeholders for this call (JSON string) |
| `orq.object_name` | Display name for the traced object |
Arbitrary key-value context attached to the span, such as `customer_tier` or `feature_flag`. Filterable in the [**Traces**](/docs/ai-gateway/traces) panel.
## Guardrail rules and routing rules
These attributes reflect static rule enforcement: which routing rule or guardrail matched this request. For dynamic model selection (fallback, auto-router, load balancer), see [Routing, fallback, and model selection](#routing-fallback-and-model-selection).
| Attribute | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `orq.routing_rule.id` | [Routing rule](/docs/ai-gateway/configuration/routing-rules) that matched |
| `orq.guardrail_rule.ids` | IDs of [Guardrail](/docs/ai-gateway/configuration/guardrails) rules that matched this request (array of strings) |
| `orq.guardrail.enabled` | Span is a blocking guardrail check |
| `orq.guardrail.action` | Action taken, e.g. `"block"` |
Use these to debug why a request was blocked or routed by a rule.
## Guardrails
On [**Guardrail**](/docs/ai-gateway/configuration/guardrails) spans:
| Attribute | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `orq.evaluator.id` | Guardrail ID |
| `orq.evaluator.type` | Guardrail type, e.g. `"llm_judge"`, `"regex"`, `"similarity"` |
| `orq.evaluator.version` | Guardrail version |
| `orq.evaluator.output_type` | Output type, e.g. `"boolean"`, `"score"`, `"label"` |
| `orq.evaluation.stage` | `"input"` when the guardrail ran before the model call (checking the prompt); `"output"` when it ran after (checking the response) |
Score, pass, and fail results also appear via standard `gen_ai.evaluation.*` attributes.
## Routing, fallback, and model selection
These attributes reflect dynamic model selection at runtime: which model was actually chosen, and why it differed from the one requested. For static rule enforcement, see [Guardrail rules and routing rules](#guardrail-rules-and-routing-rules).
| Attribute | Description |
| ---------------------------------- | ------------------------------------------------------------------------- |
| `orq.fallback.index` | Attempt number (`0` = primary, `1` = first fallback, ...) |
| `orq.fallback.previous_model` | Model that failed |
| `orq.fallback.previous_error` | Error that triggered fallback |
| `orq.auto_router.selected_model` | Model chosen by [auto-router](/docs/ai-gateway/auto-router) |
| `orq.auto_router.strong_model` | High-capability candidate |
| `orq.auto_router.economical_model` | Cost-efficient candidate |
| `orq.auto_router.profile` | Auto-router profile |
| `orq.load_balancer.selected_model` | Model chosen by [load balancer](/docs/ai-gateway/features/load-balancing) |
| `orq.load_balancer.original_model` | Originally requested model |
Use these to explain cost differences and latency spikes when routing changed the model.
## Framework source
| Attribute | Description |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `orq.trace.framework.name` | Framework that emitted the trace, e.g. `"langchain"`, `"openai-agents"`, `"llama-index"` |
Use this to distinguish traces emitted directly by the **AI Gateway** from those produced by an external framework.
## Webhook example
A typical LLM webhook payload includes these attributes in the `data.attributes` block:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"orq.organization_id": "3d4c4097-3ad7-48f8-965e-71d8d25ddb1b",
"orq.workspace_id": "391ff8f8-95cd-49bd-9e28-eddba2d570b8",
"orq.product": "router",
"orq.span_type": "span.chat_completion",
"orq.model.id": "85b18e5b-76a0-48dc-99b5-5738c35c9c85",
"orq.model.provider": "openai",
"orq.model.type": "chat",
"orq.model.is_private": false,
"orq.billing.input_cost": 0.0000012,
"orq.billing.output_cost": 0.0000054,
"orq.billing.total_cost": 0.0000066,
"orq.billing.billable": false,
"orq.billing.pricing_tier": "standard"
}
```
See [Webhooks](/docs/ai-studio/organization/webhooks) for the full envelope shape.