Section ID:
Values of
Values of
DOC-API-MODEL-schema-1ju9tclufp#overview
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.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1ju9tclufp#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1ju9tclufp#fields
| Usage | Fields and validation |
|---|---|
| In responses | View fields |
In responses
Section ID: DOC-API-MODEL-schema-1ju9tclufp#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-observationidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-observationidobservationId | string | Optional | Identifier of the evaluation observation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-traceidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-traceidtraceId | string | Optional | Identifier of the evaluation trace. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-parentobservationidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-parentobservationidparentObservationId | string | Optional | Identifier of the parent observation within the trace. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-typeSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-typetype | 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; explicit presence | Observation kind reported by the evaluation provider. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-nameSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-namename | string | Optional | Operation name recorded for the evaluation observation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-levelSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-levellevel | string (OBSERVATION_LEVEL_DEBUG, OBSERVATION_LEVEL_DEFAULT, OBSERVATION_LEVEL_WARNING, OBSERVATION_LEVEL_ERROR) or integer (int32) | Optional; explicit presence | Observation log level reported by the evaluation provider. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-statusmessageSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-statusmessagestatusMessage | string | Optional | Diagnostic text explaining the reported state. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-starttimeSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-starttimestartTime | string (date-time) | Optional | Beginning of the time interval represented by this operation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-endtimeSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-endtimeendTime | string (date-time) | Optional | End of the time interval represented by this operation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-completionstarttimeSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-completionstarttimecompletionStartTime | string (date-time) | Optional | Time to first token, generations only. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-latencysecondsSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-latencysecondslatencySeconds | number (double) or string (NaN, Infinity, -Infinity) | Optional | Elapsed observation latency, in seconds. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-inputjsonSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-inputjsoninputJson | string | Optional | Evaluation input serialized as JSON. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-outputjsonSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-outputjsonoutputJson | string | Optional | Evaluation output serialized as JSON. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-metadatajsonSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-metadatajsonmetadataJson | string | Optional | Additional attributes serialized as a JSON object. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-modelSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-modelmodel | string | Optional | Model identifier recorded for the evaluated generation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-modelparametersjsonSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-modelparametersjsonmodelParametersJson | string | Optional | Model parameters recorded as a serialized JSON object. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-inputtokensSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-inputtokensinputTokens | string (int64) | Optional | Input-token usage reported for the evaluated generation. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-outputtokensSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-outputtokensoutputTokens | string (int64) | Optional | Output-token usage reported for the evaluated generation. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-totaltokensSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-totaltokenstotalTokens | string (int64) | Optional | Total token usage reported for the evaluated generation or aggregate. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-inputcostSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-inputcostinputCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Cost attributed to model input by the evaluation provider. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-outputcostSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-outputcostoutputCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Cost attributed to model output by the evaluation provider. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-totalcostSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-totalcosttotalCost | number (double) or string (NaN, Infinity, -Infinity) | Optional | Total cost reported for the evaluated generation or aggregate. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-environmentSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-environmentenvironment | string | Optional | Environment label attached to the evaluation record. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-versionSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-versionversion | string | Optional | Version of the resource represented by this message. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-promptnameSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-promptnamepromptName | string | Optional | Name of the versioned prompt associated with the generation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-promptversionSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-promptversionpromptVersion | string (int64) | Optional | Version of the prompt associated with the generation. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-scoresSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-scoresscores | Array of Score | Optional | Evaluation scores returned for the selected objects or query. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-commentcountSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-commentcountcommentCount | string (int64) | Optional | Number of comments reported on the evaluation object. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-conversationidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-conversationidconversationId | string | Optional | Identifier of the conversation associated with this evaluation observation, when recorded. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-sourceusermessageidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-sourceusermessageidsourceUserMessageId | string | Optional | Identifier of the user message that opened the evaluated generation turn. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-profileidSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-profileidprofileId | string | Optional | Identifier of the agent profile associated with the generation. |
Section ID: DOC-API-MODEL-schema-1ju9tclufp#field-confighashSection ID: DOC-API-MODEL-schema-1ju9tclufp#response-field-confighashconfigHash | 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
Section ID: DOC-API-MODEL-schema-1ju9tclufp#response-values-type
Semantic category of a trace observation, including categories accepted from upstream even when the platform does not emit them. Current emitters produce GENERATION, TOOL, RETRIEVER and SPAN; the other declared categories can still describe upstream observations.
| Value | No. | Form | Meaning |
|---|---|---|---|
OBSERVATION_TYPE_SPAN | 0 | Canonical | A timed unit of work represented as a span. |
OBSERVATION_TYPE_GENERATION | 1 | Canonical | A model-generation operation and its recorded inputs, outputs and usage. |
OBSERVATION_TYPE_EVENT | 2 | Canonical | A point-in-time event rather than a timed operation. |
OBSERVATION_TYPE_TOOL | 3 | Canonical | Execution of a tool call. |
OBSERVATION_TYPE_RETRIEVER | 4 | Canonical | Retrieval of supporting documents or other context. |
OBSERVATION_TYPE_AGENT | 5 | Canonical | An agent-level operation reported in the trace. |
OBSERVATION_TYPE_CHAIN | 6 | Canonical | A sequence or chain of related processing steps. |
OBSERVATION_TYPE_EMBEDDING | 7 | Canonical | Computation of vector embeddings. |
OBSERVATION_TYPE_EVALUATOR | 8 | Canonical | An evaluator operation that assesses another result. |
OBSERVATION_TYPE_GUARDRAIL | 9 | Canonical | A guardrail check on inputs, outputs or processing. |
Values of level
Section ID: DOC-API-MODEL-schema-1ju9tclufp#response-values-level
Diagnostic severity attached to an evaluation observation.
| Value | No. | Form | Meaning |
|---|---|---|---|
OBSERVATION_LEVEL_DEBUG | 0 | Canonical | Detailed diagnostic information intended for debugging. |
OBSERVATION_LEVEL_DEFAULT | 1 | Canonical | Ordinary observation information without an elevated warning or error level. |
OBSERVATION_LEVEL_WARNING | 2 | Canonical | A condition reported at warning severity. |
OBSERVATION_LEVEL_ERROR | 3 | Canonical | A condition reported at error severity. |
Where used
Section ID: DOC-API-MODEL-schema-1ju9tclufp#where-used
| Reference | Relationship |
|---|---|
| Get a trace | POST /api/v1/evals/get-trace |
| List observations | POST /api/v1/evals/list-observations |
Models containing this value
| Model | Relationship |
|---|---|
| TraceDetail | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1ju9tclufp