> ## 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. Find every attribute emitted by Orq.ai across traces, webhook payloads, and trace exports.
`orq.*` attributes are OpenTelemetry span attributes emitted by **Orq.ai** on every trace span. They appear in the [**Traces**](/ai-studio/observability/traces) panel, in [LLM webhook](/ai-studio/organization/webhooks) payloads, and in trace exports. Core attributes appear on every span; attributes in **Invoked resources**, **Evaluators**, 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.*` |
| [Evaluators](#evaluators) | `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` |
| [MCP](#mcp) | `mcp.method.name`, `mcp.session.id`, `mcp.protocol.version`, `mcp.resource.uri`, `server.address` |
| [Tool calls](#tool-calls) | `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.description`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result` |
## Span type
Classifies the kind of work a span represents. Use `orq.span_type` to filter spans by operation type in the [**Traces**](/ai-studio/observability/traces) view or [LLM webhook](/ai-studio/organization/webhooks) payloads.
| Attribute | Description |
| --------------- | ------------------- |
| `orq.span_type` | Span operation type |
Common values:
| Value | Meaning |
| ------------------------ | ---------------------------------------------------------- |
| `span.chat_completion` | Chat completion call |
| `span.responses` | [Responses API](/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` | Smart 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.*`. See [Token usage](#token-usage) below.
## Token usage
Token counts follow the OpenTelemetry `gen_ai.usage.*` convention. Detailed breakdowns are present only when the provider reports them.
| Attribute | Description |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| `gen_ai.usage.input_tokens` | Input tokens, including any cached or cache-written tokens (int) |
| `gen_ai.usage.output_tokens` | Output tokens (int) |
| `gen_ai.usage.total_tokens` | Input plus output tokens (int) |
| `gen_ai.usage.prompt_tokens_details.cached_tokens` | Input tokens read from the prompt cache (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_tokens` | Input tokens written to the prompt cache, across all TTLs (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_5m_tokens` | Cache write tokens with the 5-minute TTL. Anthropic only (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_1h_tokens` | Cache write tokens with the 1-hour TTL. Anthropic only (int) |
| `gen_ai.usage.prompt_tokens_details.audio_tokens` | Audio input tokens (int) |
| `gen_ai.usage.completion_tokens_details.reasoning_tokens` | Reasoning or thinking tokens (int) |
| `gen_ai.usage.completion_tokens_details.audio_tokens` | Audio output tokens (int) |
The cached and cache-written counts are subsets of `gen_ai.usage.input_tokens`. Their cost is reported separately in `orq.billing.cache_read_cost` and `orq.billing.cache_write_cost`. See [Prompt caching](/ai-gateway/features/prompt-caching#cache-usage-in-traces) for how these appear per API.
## 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**](/ai-studio/observability/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 that handled the request, e.g. `"router"`, `"agents"`, `"spreadsheets"` |
Filter traces by project, or assign cost to an [**Identity**](/ai-studio/observability/identities).
## Invoked resources
Links a trace to the **Orq.ai** resources that served the request.
| Attribute | Description |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| `orq.deployment_id` | [**Deployment**](/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**](/ai-studio/prompts/prompts) resource |
| `orq.knowledge_id` | [Knowledge base](/ai-studio/ai-engineering/knowledge-bases) 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](/ai-studio/ai-engineering/run-agents) |
| `orq.workflow.run_id` | Workflow run |
Use these to answer: which [deployment](/ai-studio/ai-engineering/deployments), [prompt](/ai-studio/prompts/prompts), [knowledge base](/ai-studio/ai-engineering/knowledge-bases), [schedule](/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**](/ai-studio/observability/threads) ID: groups turns within a single conversation |
| `orq.session_id` | Session ID: groups requests that share the same value across conversations |
| `orq.agent_execution_id` | A single [**Agent**](/ai-studio/ai-engineering/run-agents) run |
`orq.thread_id` groups individual turns into a conversation. `orq.session_id` groups requests across conversations for broader session tracking; when a request carries both, `orq.thread_id` determines the grouping. Pass `orq.thread_id` to group related turns in the [**Threads**](/ai-studio/observability/threads) view.
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**](/ai-studio/observability/traces) view and in [Trace Automations](/ai-studio/observability/automations).
Filterable attributes follow ingest limits: string values longer than 512 bytes are not kept as filterable attributes, and attribute keys longer than 512 bytes are dropped. Up to 200 attribute keys per span are kept, raise the limit to at most 1000 with the `orq.attribute_keys_limit` attribute. Selection is deterministic: keys prefixed `gen_ai.` or `orq.` are kept first, then the remaining keys alphabetically. The full span payload, including values past these limits, stays available on the span detail.
## Guardrail rules and routing rules
These attributes reflect static rule enforcement: which routing rule or guardrail matched this request. For dynamic model selection (fallback, Smart Router, load balancer), see [Routing, fallback, and model selection](#routing-fallback-and-model-selection).
| Attribute | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `orq.routing_rule.id` | [Routing rule](/ai-gateway/configuration/routing-rules) that matched |
| `orq.guardrail_rule.ids` | IDs of [Guardrail](/ai-gateway/configuration/guardrail-rules) 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.
## Evaluators
On [**Evaluator**](/ai-studio/optimize/evaluators) and [**Guardrail**](/ai-gateway/configuration/guardrail-rules) spans:
| Attribute | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `orq.evaluator.id` | Evaluator ID |
| `orq.evaluator.type` | Evaluator type, e.g. `"llm_judge"`, `"regex"`, `"similarity"` |
| `orq.evaluator.version` | Evaluator version |
| `orq.evaluator.output_type` | Output type, e.g. `"boolean"`, `"score"`, `"label"` |
| `orq.evaluation.stage` | `"input"` when the evaluator 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.
`gen_ai.evaluation.explanation` carries free-text reasoning. Explanations longer than 512 bytes appear shortened with an ellipsis in list views and tooltips; the full text remains on the span detail. Substring filters are not offered on this attribute.
## 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 the [Smart Router](/ai-gateway/smart-router) |
| `orq.auto_router.strong_model` | High-capability candidate |
| `orq.auto_router.economical_model` | Cost-efficient candidate |
| `orq.auto_router.profile` | Smart Router profile |
| `orq.load_balancer.selected_model` | Model chosen by [load balancer](/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 **Orq.ai** from those produced by an external framework.
## MCP
On [**MCP tool**](/ai-studio/observability/mcp-tracing) spans (`span.tool` with `gen_ai.tool.type = "mcp"`):
| Attribute | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `mcp.method.name` | MCP method called, e.g. `tools/call`, `tools/list`, `resources/read` |
| `mcp.session.id` | MCP session identifier. External instrumentation only; never set on platform-managed spans |
| `mcp.protocol.version` | MCP protocol version negotiated during initialization. Set by external instrumentation, and by the MCP gateway on its own spans |
| `mcp.resource.uri` | MCP resource URI, present on resource reads. External instrumentation only |
| `server.address` | MCP server hostname, e.g. `mcp.linear.app`. Platform-managed spans only; not retained on externally instrumented OTLP spans |
## Tool calls
On `span.tool` spans:
| Attribute | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `gen_ai.tool.name` | Tool name as exposed to the model. Prefixed with the server key, e.g. `linear_mcp__create_issue`, when multiple MCP servers are configured |
| `gen_ai.tool.type` | Tool type, `"function"` or `"mcp"` |
| `gen_ai.tool.description` | Tool description from the server's catalog. External instrumentation only; never set on platform-managed spans |
| `gen_ai.tool.call.id` | Unique identifier for this tool call |
| `gen_ai.tool.call.arguments` | JSON-encoded arguments (sensitive content) |
| `gen_ai.tool.call.result` | JSON-encoded result (sensitive content) |
On platform-managed spans, `gen_ai.tool.call.arguments` and `gen_ai.tool.call.result` are captured by default, with secret redaction and the [Data Compliance](/ai-studio/organization/data-compliance) masking rules applied before storage. Externally instrumented clients are not covered: masking runs only for spans that carry the `orq.masking_options` attribute, which platform components set, so values exported over OTLP are stored as received. Mask sensitive data before export.
## 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](/ai-studio/organization/webhooks) for the full envelope shape.