Schema Reference

When Parseable receives GenAI traces at the /v1/traces endpoint, it flattens the nested OTel JSON into queryable rows for both spans and span events. This page documents the columns you are most likely to query.

Span Hierarchy

A single agent invocation produces a tree of spans sharing the same span_trace_id:

span_trace_id: abc123
|
+-- [root] invoke-agent (gen_ai.operation.name = "invoke_agent")
      |
      +-- chat gpt-4o (gen_ai.operation.name = "chat")
      |     +-- event: gen_ai.client.inference.operation.details
      |
      +-- execute_tool search_api (gen_ai.operation.name = "execute_tool")
      |     +-- attributes: gen_ai.tool.call.arguments
      |     +-- attributes: gen_ai.tool.call.result
      |
      +-- chat gpt-4o (gen_ai.operation.name = "chat")
            +-- event: gen_ai.client.inference.operation.details
            +-- event: gen_ai.evaluation.result

Key points:

Span rows have event_name IS NULL. These contain the gen_ai.* attributes, token counts, and Parseable-enriched columns.
Event rows have event_name set, usually gen_ai.client.inference.operation.details or gen_ai.evaluation.result for native GenAI instrumentation. Parseable flattens event attributes with an event_ prefix, so event content and event metadata stay queryable alongside the parent span.
Use span_parent_span_id to reconstruct the call tree within a trace.

Core Trace Columns

These are standard OpenTelemetry span fields, present on every row.

Column	Type	Description
`span_trace_id`	String	Unique identifier for the entire trace (shared across all spans in one agent run).
`span_span_id`	String	Unique identifier for this individual span.
`span_parent_span_id`	String	Span ID of the parent span. Empty string for root spans.
`span_name`	String	Human-readable span name (e.g., `chat gpt-4o`, `execute_tool search`).
`span_kind`	Int	OTel span kind numeric value (0=Unspecified, 1=Internal, 2=Server, 3=Client).
`span_kind_description`	String	Human-readable span kind (e.g., `SPAN_KIND_CLIENT`).
`span_start_time_unix_nano`	BigInt	Span start time in nanoseconds since epoch.
`span_end_time_unix_nano`	BigInt	Span end time in nanoseconds since epoch.
`span_status_code`	Int	Status code: 0=Unset, 1=OK, 2=Error.
`span_status_description`	String	Human-readable status (e.g., `STATUS_CODE_OK`).
`span_status_message`	String	Error message when `span_status_code = 2`.
`span_trace_state`	String	W3C trace state string.
`span_flags`	Int	Span flags bitmask.
`span_flags_description`	String	Human-readable span flags.
`span_dropped_attributes_count`	Int	Number of attributes dropped due to limits.
`span_dropped_events_count`	Int	Number of events dropped due to limits.
`span_dropped_links_count`	Int	Number of links dropped due to limits.
`p_timestamp`	Timestamp	Parseable ingest timestamp.
`p_metadata`	String	Parseable metadata field.
`p_tags`	String	Parseable tags field.
`service.name`	String	OTel resource attribute identifying the service.
`scope_name`	String	Instrumentation scope name.
`scope_version`	String	Instrumentation scope version.
`schema_url`	String	OTel schema URL.

GenAI Identity and Operation

Columns that identify the GenAI operation being performed.

Column	Type	Description
`gen_ai.operation.name`	String	Type of operation: `chat`, `text_completion`, `embeddings`, `execute_tool`, `invoke_agent`.
`gen_ai.system`	String	GenAI provider system identifier (e.g., `openai`, `anthropic`, `cohere`).
`gen_ai.provider.name`	String	Provider name when different from system.
`gen_ai.conversation.id`	String	Unique identifier for a multi-turn conversation thread.

Model Request

Columns capturing the parameters sent to the model.

Column	Type	Description
`gen_ai.request.model`	String	Model requested (e.g., `gpt-4o`, `claude-3-opus-20240229`).
`gen_ai.request.temperature`	Float	Sampling temperature.
`gen_ai.request.top_p`	Float	Nucleus sampling parameter.
`gen_ai.request.top_k`	Int	Top-k sampling parameter.
`gen_ai.request.max_tokens`	Int	Maximum tokens requested for the response.
`gen_ai.request.seed`	Int	Random seed for reproducibility.
`gen_ai.request.frequency_penalty`	Float	Frequency penalty parameter.
`gen_ai.request.presence_penalty`	Float	Presence penalty parameter.
`gen_ai.request.stop_sequences`	String	Stop sequences (JSON array as string).

Model Response

Columns capturing what the model returned.

Column	Type	Description
`gen_ai.response.id`	String	Provider-assigned response ID (e.g., `chatcmpl-abc123`).
`gen_ai.response.model`	String	Actual model used (may differ from requested, e.g., `gpt-4o-2024-08-06`).
`gen_ai.response.finish_reasons`	String	Reason the model stopped generating (JSON array, e.g., `["stop"]`, `["tool_calls"]`).

Token Usage

Columns tracking token consumption per span.

Column	Type	Description
`gen_ai.usage.input_tokens`	Int	Number of input (prompt) tokens consumed.
`gen_ai.usage.output_tokens`	Int	Number of output (completion) tokens generated.
`gen_ai.usage.input_token_details.cached_tokens`	Int	Number of input tokens served from cache.
`gen_ai.usage.reasoning.output_tokens`	Int	Number of output tokens used for reasoning, when reported by the provider.

Message and Operation Details

These columns are used when your instrumentation records native GenAI message details on the span itself. If your SDK records them on the gen_ai.client.inference.operation.details event instead, the same fields appear with the event_ prefix on event rows.

Column	Type	Description
`gen_ai.input.messages`	String	Chat history provided to the model. Messages use native roles such as `user`, `assistant`, and `tool`.
`gen_ai.output.messages`	String	Messages returned by the model. The model or agent output is represented as an `assistant` message.
`gen_ai.system_instructions`	String	System instructions when the provider or framework keeps them separate from the chat history.
`gen_ai.tool.definitions`	String	Tool definitions available to the model for that request.

Agent

Columns specific to agent-level spans (where gen_ai.operation.name = 'invoke_agent').

Column	Type	Description
`gen_ai.agent.name`	String	Name of the agent.
`gen_ai.agent.id`	String	Unique identifier for the agent instance.
`gen_ai.agent.description`	String	Human-readable description of the agent's purpose.

Tool Execution

Columns specific to tool call spans (where gen_ai.operation.name = 'execute_tool').

Column	Type	Description
`gen_ai.tool.name`	String	Name of the tool invoked (e.g., `search_api`, `calculator`).
`gen_ai.tool.type`	String	Type of tool (e.g., `function`, `retrieval`, `code_interpreter`).
`gen_ai.tool.call.id`	String	Provider-assigned tool call ID.
`gen_ai.tool.call.arguments`	String	JSON string of arguments passed to the tool.
`gen_ai.tool.call.result`	String	JSON string or text of the tool execution result.

Event Columns

These columns appear on event rows where event_name is not null. The exact set depends on which event attributes your instrumentation emits.

Column	Type	Description
`event_name`	String	Event type, usually `gen_ai.client.inference.operation.details` or `gen_ai.evaluation.result` for native GenAI instrumentation.
`event_gen_ai.operation.name`	String	Operation name repeated on the event, for example `chat`.
`event_gen_ai.provider.name`	String	Provider name repeated on the event.
`event_gen_ai.request.model`	String	Requested model repeated on the event.
`event_gen_ai.input.messages`	String	Input messages emitted through the OpenTelemetry GenAI operation details event.
`event_gen_ai.output.messages`	String	Output messages emitted through the OpenTelemetry GenAI operation details event.
`event_gen_ai.system_instructions`	String	System instructions emitted through the OpenTelemetry GenAI operation details event.
`event_gen_ai.tool.definitions`	String	Tool definitions available to the model for that request.
`event_gen_ai.evaluation.name`	String	Name of the evaluator or evaluation metric when `gen_ai.evaluation.result` is emitted.
`event_gen_ai.evaluation.score.label`	String	Human-readable evaluation label, for example `correct`, `incorrect`, `pass`, or `fail`.
`event_gen_ai.evaluation.score.value`	Float	Numeric evaluation score when available.
`event_gen_ai.evaluation.explanation`	String	Free-form explanation for the evaluation result when available.
`event_error.type`	String	Error type when the operation-details event is emitted for a failed model operation.
`event_time_unix_nano`	BigInt	Event timestamp in nanoseconds since epoch.
`event_dropped_attributes_count`	Int	Number of event attributes dropped due to limits.

Parseable-Enriched Columns

These columns are computed server-side by Parseable at ingest time. They do not exist in the raw OTel data.

Column	Type	Description
`p_genai_tokens_total`	Int	Sum of `gen_ai.usage.input_tokens` + `gen_ai.usage.output_tokens`.
`p_genai_tokens_per_sec`	Float	Throughput: `output_tokens / (span_duration_seconds)`. Useful for comparing model and provider performance.
`p_genai_duration_ms`	Float	Span duration in milliseconds, computed from `span_end_time_unix_nano - span_start_time_unix_nano`.

Schema Reference

On this page