Skip to main content
PATCH
Update trace
You are reading the docs of Galtea 5.16. Read this page in the latest version.

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); an envelope { assistant_message, content: [{ type, uri, transcript }] } carries audio or file parts. A file part with a non-empty uri is a file, and an answer that is only files needs no scalar. A file element with no uri belongs to the customer: it is stored as sent beside a scalar, and refused without one.

Example:

"Model response text"

retrievalContext
string
Example:

"Retrieved context document"

error
string | null

Error message explaining why this trace failed or was skipped

latency
number

Latency in milliseconds

input

Agent input for this turn. Plain text by default; for voice, an envelope carrying audio content parts. Each element of a content array is read on its own. A file part is a Galtea file when its uri names a Galtea storage key (files/<organization>/<32 hex>.<extension>, on any host): it is stored signature-free and checked as on a test case input (at most 20 files and 20 MB, an accepted file type, a file of this organization), otherwise 400. A Galtea file missing from storage is stored signature-free without its sizeBytes, and every other element as sent.

status
enum<string>

Trace lifecycle status. Becomes GENERATED automatically when actualOutput is written and no status is given.

Available options:
PENDING,
GENERATED,
FAILED,
SKIPPED
inputTokens
integer

Input tokens sent to the model. Recounted from the input when the request carries an input and omits this, unless the row keeps its cost (see cost). At most 2147483647, else 400.

outputTokens
integer

Output tokens generated by the model. Recounted from the output when the request carries an output and omits this, unless the row keeps its cost (see cost) or is a PENDING turn that already holds a reported count and has no output yet. At most 2147483647, else 400.

cacheReadInputTokens
integer

Input tokens read from the model cache. At most 2147483647, else 400.

tokens
integer

Total tokens. A value you send here is stored as sent. Omitted, it is re-derived from the three counts above when the request sends an input, an output, a count, a rate or the cost, unless the row keeps its cost (see cost). At most 2147483647, else 400.

cost
number

Total cost. A value you send here is stored as sent. Omitted, it is re-derived from the token counts and the per-token rates when the request sends a count or a rate. A request that sends an input or an output and no count or rate re-derives it at the stored rates, but keeps a cost those counts and rates do not produce, such as a stated cost or a cost summed over spans on several models. A request that sends only tokens keeps the cost.

costPerInputToken
number

Price of one input token. Replaced by the span rates when the turn's spans report usage; null when they use different rates. A cost you state is kept.

costPerOutputToken
number

Price of one output token. Replaced by the span rates when the turn's spans report usage; null when they use different rates. A cost you state is kept.

costPerCacheReadInputToken
number

Price of one cache-read token. Replaced by the span rates when the turn's spans report usage; null when they use different rates. A cost you state is kept.

conversationSimulatorVersion
string | null

Version of Galtea's conversation simulator that produced the user message

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: "..." }. A content array of parts (audio or file) can sit beside an optional user_message. Each element of a content array is read on its own. A file part is a Galtea file when its uri names a Galtea storage key (files/<organization>/<32 hex>.<extension>, on any host): it is stored signature-free and checked as on a test case input (at most 20 files and 20 MB, an accepted file type, a file of this organization), otherwise 400. A Galtea file missing from storage is stored signature-free without its sizeBytes, and every other element as sent. A metric scores a Galtea file only when its judge model reads that kind of file (PNG, JPEG, WebP, GIF or PDF); any other metric that reads this side is skipped, except a human evaluation or self-hosted one, and the reason names the file.

Example:
actualOutput

The agent turn output. Plain text by default (the scored scalar). An envelope { assistant_message, content: [...] } carries a content array of parts (audio or file) beside an optional assistant_message — the scored scalar stays the canonical transcript, and an answer that is only a file carries no scalar at all. A metric scores a Galtea file only when its judge model reads that kind of file (PNG, JPEG, WebP, GIF or PDF); any other metric that reads this side is skipped, except a human evaluation or self-hosted one, and the reason names the file.

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

droppedSpanCount
integer | null

How many spans sent with this trace were refused, for example a span with an empty name or a negative latency. Null means none were refused.

Example:

2

conversationSimulatorVersion
string | null
Example:

"1.0.0"

traceId
string | null

W3C trace ID Galtea sends in the traceparent header on this Direct Inference turn. Stored when the turn starts. This is the OpenTelemetry trace id, not the id of this Galtea trace, which is id.

Example:

"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

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

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