Skip to main content

​
Returns

Returns a Trace object.

​
Example

​
Answering with a file

For a product whose answer is a document, name the local files and the SDK uploads them:
Leave output out when the file is the whole answer:

​
Reading a document as input

For a product that reads documents, name the local files and the SDK uploads them. Galtea stores each file without its upload signature, so the trace keeps working after the upload link expires:
Leave input out when the file is the whole input:

​
Parameters

​
string
The session ID to log the trace to.
Instead of a session_id, you can reference an existing session by its own conversation id (see the section below). Provide exactly one of the two.
If you already created the session via the sessions API with your own custom_id, reference it here with session_custom_id plus a version_id or product_id to append traces to it. If no matching session exists, the call returns a 400 error — create it first via the sessions API.
​
string
Your own conversation id, as an alternative to session_id. Galtea finds an existing session with this id (per version); the session is not created here. Requires version_id or product_id.
​
string
The version the session is anchored to when using session_custom_id.
Provide version_id or product_id (at least one) when using session_custom_id. If both are given, version_id wins and product_id is ignored.
​
string
Product anchor used when no version_id is given with session_custom_id: Galtea finds the session with this custom id under the product (across its versions).
If no session matches the session_custom_id and anchor, the call returns a 400 error. Create the session first via the sessions API.
​
string | object
The input text/prompt. A dict is stored as sent. Galtea reads each element of its content list on its own: a Galtea file is stored without its upload signature and must be an accepted type, with at most 20 files and 20 MB. Every other element, such as a file URL on your own host, is stored as sent. A Galtea file of another organization fails the call with a 400. A metric scores a Galtea file only when its judge model reads that kind of file. See Content Parts.
​
string | object
The generated output/response. A dict is stored as sent. Galtea reads each element of its content list on its own: a Galtea file is stored without its upload signature and must be an accepted type, with at most 20 files and 20 MB. Every other element, such as a file URL on your own host, is stored as sent. A Galtea file of another organization fails the call with a 400. A metric scores a Galtea file only when its judge model reads that kind of file. See Content Parts.
​
list[str]
Files the turn received, for a product that reads documents. Each entry is a local path the SDK uploads, or a Galtea file reference from an earlier upload, such as trace.input_files[0].uri, which is attached without uploading it again. Any other URL raises a ValueError before anything is uploaded.input stays optional, so a turn can receive files and no text. The input is then the files alone.One input accepts at most 20 files, 20 MB in total, of the same types a test case input accepts. See Upload Output File for the list.
A metric scores a file only when its judge model reads that kind of file. Only a Galtea file, one you uploaded to Galtea, is sent to a judge. A file on your own host is stored as sent and never reaches a judge, so it never skips an evaluation: the judge reads the text beside it. The kinds a judge reads depend on its model, and the model picker of the metric form shows them for each model. A judge is sent PNG, JPEG, WebP, GIF and PDF files only. The other accepted types are stored, and a Galtea input file of those types still reaches your endpoint, but no judge reads them. The rule is the same for the input and the output, and a metric that reads conversation_turns reads both sides of every turn.Before an evaluation runs, Galtea checks every Galtea file on each side the metric reads. One file the judge would not read skips the evaluation, whatever text sits beside it. A skipped evaluation costs no credits, and its reason names the file, its turn and what refused it:
  • The judge model cannot read that kind of file.
  • The model catalog does not say whether the judge model reads it.
  • The metric names no judge model.
  • The metric is DeepEval-based: those judges are sent text only.
  • The metric is deterministic: it compares text without a model.
  • The metric is a classifier metric: it is sent text only.
  • The file is a type no judge reads, such as DOCX, CSV or TIFF, or an audio file: a judge reads audio only through its transcript.
When the evaluator then reads a Galtea file to send it, it skips the evaluation if the file no longer exists in storage, is empty, or is larger than the 20 MB a judge can receive. The reason names the file.Audio input with no transcript is a separate case. A metric that reads the input is skipped when no turn of the session has input text or a Galtea input file, and a turn’s audio carries no transcript. Text or a Galtea file on another turn is enough, and the reason, Evaluators read an audio input through its transcript, and no turn carries one., names no file.Human evaluation and self-hosted metrics are never skipped for a file or for audio. On deployments that do not send files to the judge, the evaluator also skips a metric whose judge would read the file, and the reason names the file.To have the content scored, pick a metric whose judge model reads that kind of file, or log the text your pipeline extracted as the turn input or output, without the file. See Troubleshooting skipped evaluations.
​
list[str]
Files the turn answers with, for a product whose reply is a document. Each entry is a local path the SDK uploads, or a Galtea file reference from an earlier upload, which is attached without uploading it again. Any other URL raises a ValueError before anything is uploaded.output stays optional, so a turn can answer with files and no text. Its actual_output then reads back as None, and the envelope is in actual_output_data.One output accepts at most 20 files, 20 MB in total, of the same types an input accepts. See Upload Output File for the list and for reusing one upload across turns.Output files follow the same rule as input_file_paths above.
​
string
Context retrieved for RAG systems.
When you set retrieval_context, Galtea also records it as a RETRIEVER span on this trace.
​
float
Latency in milliseconds.
​
dict[str, int]
Information about token usage during the model call. Possible keys include:
  • input_tokens: Number of input tokens sent to the model.
  • output_tokens: Number of output tokens generated by the model.
  • cache_read_input_tokens: Number of input tokens read from the cache.
​
dict[str, float]
Information about the cost per token during the model call. Possible keys include:
  • cost_per_input_token: Cost per input token sent to the model.
  • cost_per_output_token: Cost per output token generated by the model.
  • cost_per_cache_read_input_token: Cost per input token read from the cache.
​
string
The version of Galtea’s conversation simulator used to generate the user message (input). This should only be provided when logging a conversation that was generated using the simulator.
​
str | TraceStatus
The initial status of the trace. Accepts a case-insensitive string or a TraceStatus enum value. Valid values: PENDING, GENERATED, FAILED, SKIPPED. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.The two typical SDK flows are:
  • Omit (default) to create the trace as GENERATED — the right choice when the output is already known at create time.
  • Pass PENDING to log the trace before the model call completes, then transition to GENERATED or FAILED via update() once the call resolves.
Passing FAILED or SKIPPED directly is supported for callers that want to log a terminal-state trace explicitly (e.g. recording a known-bad turn or a skipped step).