Skip to main content
PATCH
Update trace

Authorizations

Authorization
string
header
required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Path Parameters

id
string
required

Trace ID

Body

application/json
actualOutput

Agent output. Plain text by default (the scored scalar); for voice, an envelope { assistant_message, content: [{ type, uri, transcript }] } carrying audio parts. An audio part without a transcript is rejected with a 400.

Example:

"Model response text"

retrievalContext
string
Example:

"Retrieved context document"

error
string | null

Error message explaining why this trace failed or was skipped

latency
integer

Response

Trace updated successfully

A trace: one conversation turn, holding the input and the agent output. The schema name, the /inferenceResults path and every inferenceResult* field still carry the old name of this entity, "inference result". Only the wording changed so far; the wire contract is renamed in a later API release.

id
string
Example:

"ir_123"

sessionId
string
Example:

"session_123"

userId
string | null
Example:

"user_123"

index
integer

Order index within the session

Example:

0

status
enum<string>
Available options:
PENDING,
GENERATED,
FAILED,
SKIPPED
Example:

"PENDING"

error
string | null

Error message explaining why this trace failed or was skipped

Example:

null

input
object | null

Structured input data. For plain text input, format is { user_message: "..." }

Example:
actualOutput

The agent turn output. Plain text by default (the scored scalar). For voice turns, an envelope { assistant_message, content: [{ type, uri, transcript }] } carrying audio parts — the scored scalar stays the canonical transcript.

Example:

"Model response"

latency
integer | null
Example:

150

inputTokens
integer | null
Example:

100

outputTokens
integer | null
Example:

50

cacheReadInputTokens
integer | null
Example:

20

tokens
integer | null

Total tokens

Example:

150

costPerInputToken
number | null
Example:

0.00001

costPerOutputToken
number | null
Example:

0.00003

costPerCacheReadInputToken
number | null
Example:

0.000005

cost
number | null
Example:

0.001

creditsUsed
integer | null
Example:

1

conversationSimulatorVersion
string | null
Example:

"1.0.0"

traceId
string | null

W3C trace ID for the root span created during direct inference. This is the OpenTelemetry trace id, not the id of this Galtea trace, which is id. The same trace ID is propagated to the user endpoint via the traceparent header.

Example:

"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

createdAt
string<date-time>
deletedAt
string<date-time> | null
comments
object[]

Free-form reviewer annotations on this turn, oldest first.