Observation
Timed evaluation span or generation record with model usage, inputs, outputs, and scores. A generation observation originates the profile and configuration attribution promoted to its trace; callers can read those links directly on either record.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In responses | View fields |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
observationId | string | Optional | Identifier of the evaluation observation. |
traceId | string | Optional | Identifier of the evaluation trace. |
parentObservationId | string | Optional | Identifier of the parent observation within the trace. |
type | string (OBSERVATION_TYPE_SPAN, OBSERVATION_TYPE_GENERATION, OBSERVATION_TYPE_EVENT, OBSERVATION_TYPE_TOOL, OBSERVATION_TYPE_RETRIEVER, OBSERVATION_TYPE_AGENT, OBSERVATION_TYPE_CHAIN, OBSERVATION_TYPE_EMBEDDING, OBSERVATION_TYPE_EVALUATOR, OBSERVATION_TYPE_GUARDRAIL) or integer (int32) | Optional | Observation kind reported by the evaluation provider. |
name | string | Optional | Operation name recorded for the evaluation observation. |
level | string (OBSERVATION_LEVEL_DEBUG, OBSERVATION_LEVEL_DEFAULT, OBSERVATION_LEVEL_WARNING, OBSERVATION_LEVEL_ERROR) or integer (int32) | Optional | Observation log level reported by the evaluation provider. |
statusMessage | string | Optional | Diagnostic text explaining the reported state. |
startTime | string (date-time) | Optional | Beginning of the time interval represented by this operation. |
endTime | string (date-time) | Optional | End of the time interval represented by this operation. |
completionStartTime | string (date-time) | Optional | Time to first token, generations only. |
latencySeconds | number (double) or string (NaN, Infinity, -Infinity) | Optional | Elapsed observation latency, in seconds. |
inputJson | string | Optional | Evaluation input serialized as JSON. |
outputJson | string | Optional | Evaluation output serialized as JSON. |
metadataJson | string | Optional | Additional attributes serialized as a JSON object. |
model | string | Optional | Model identifier recorded for the evaluated generation. |
modelParametersJson | string | Optional | Model parameters recorded as a serialized JSON object. |
inputTokens | string (int64) | Optional | Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$. |
outputTokens | string (int64) | Optional | Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$. |
totalTokens | string (int64) | Optional | Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$. |
inputCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Cost attributed to model input by the evaluation provider. |
outputCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Cost attributed to model output by the evaluation provider. |
totalCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Total cost reported for the evaluated generation or aggregate. |
environment | string | Optional | Environment label attached to the evaluation record. |
version | string | Optional | Version of the resource represented by this message. |
promptName | string | Optional | Name of the versioned prompt associated with the generation. |
promptVersion | integer (int32) | Optional | Version of the prompt associated with the generation. Minimum: -2147483648. Maximum: 2147483647. |
scores | Array of Score | Optional | Evaluation scores returned for the selected objects or query. |
commentCount | integer (int32) | Optional | Number of comments reported on the evaluation object. Minimum: -2147483648. Maximum: 2147483647. |
conversationId | string | Optional | Identifier of the conversation associated with this evaluation observation, when recorded. |
sourceUserMessageId | string | Optional | Identifier of the user message that opened the evaluated generation turn. |
profileId | string | Optional | Identifier of the agent profile associated with the generation. |
configHash | string | Optional | Fingerprint of the profile ID, model and resolved prompt hash used to group evaluation results. Other settings are excluded; this is not an immutable profile revision. |
Values of type
Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them.
| Value | No. | Form | Meaning |
|---|---|---|---|
OBSERVATION_TYPE_SPAN | 1 | Canonical | A timed unit of work represented as a span. |
OBSERVATION_TYPE_GENERATION | 2 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
OBSERVATION_TYPE_EVENT | 3 | Canonical | A point-in-time event rather than a timed operation. |
OBSERVATION_TYPE_TOOL | 4 | Canonical | Execution of a tool call. |
OBSERVATION_TYPE_RETRIEVER | 5 | Canonical | Retrieval of supporting documents or other context. |
OBSERVATION_TYPE_AGENT | 6 | Canonical | An agent-level operation reported in the trace. |
OBSERVATION_TYPE_CHAIN | 7 | Canonical | A sequence or chain of related processing steps. |
OBSERVATION_TYPE_EMBEDDING | 8 | Canonical | Computation of vector embeddings. |
OBSERVATION_TYPE_EVALUATOR | 9 | Canonical | An evaluator operation that assesses another result. |
OBSERVATION_TYPE_GUARDRAIL | 10 | Canonical | A guardrail check on inputs, outputs or processing. |
Values of level
Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning |
|---|---|---|---|
OBSERVATION_LEVEL_DEBUG | 1 | Canonical | Detailed diagnostic information intended for debugging. |
OBSERVATION_LEVEL_DEFAULT | 2 | Canonical | Ordinary observation information without an elevated warning or error level. |
OBSERVATION_LEVEL_WARNING | 3 | Canonical | A condition reported at warning severity. |
OBSERVATION_LEVEL_ERROR | 4 | Canonical | A condition reported at error severity. |
Where used
| Reference | Relationship |
|---|---|
| Get a trace | POST /api/v1/evals/get-trace |
| List observations | POST /api/v1/evals/list-observations |
| TraceDetail | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-observation.