Create trace
curl --request POST \
--url https://api.galtea.ai/inferenceResults \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"sessionId": "session_123",
"sessionCustomId": "my-conversation-42",
"versionId": "ver_123",
"productId": "prod_123",
"userId": "user_123",
"index": 0,
"error": "<string>",
"input": {},
"actualOutput": "Model response text",
"retrievalContext": "Retrieved context document",
"latency": 123,
"inputTokens": 123,
"outputTokens": 123,
"cacheReadInputTokens": 123,
"tokens": 123,
"costPerInputToken": 123,
"costPerOutputToken": 123,
"costPerCacheReadInputToken": 123,
"cost": 123,
"conversationSimulatorVersion": "<string>"
}
'import requests
url = "https://api.galtea.ai/inferenceResults"
payload = {
"sessionId": "session_123",
"sessionCustomId": "my-conversation-42",
"versionId": "ver_123",
"productId": "prod_123",
"userId": "user_123",
"index": 0,
"error": "<string>",
"input": {},
"actualOutput": "Model response text",
"retrievalContext": "Retrieved context document",
"latency": 123,
"inputTokens": 123,
"outputTokens": 123,
"cacheReadInputTokens": 123,
"tokens": 123,
"costPerInputToken": 123,
"costPerOutputToken": 123,
"costPerCacheReadInputToken": 123,
"cost": 123,
"conversationSimulatorVersion": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: 'session_123',
sessionCustomId: 'my-conversation-42',
versionId: 'ver_123',
productId: 'prod_123',
userId: 'user_123',
index: 0,
error: '<string>',
input: {},
actualOutput: 'Model response text',
retrievalContext: 'Retrieved context document',
latency: 123,
inputTokens: 123,
outputTokens: 123,
cacheReadInputTokens: 123,
tokens: 123,
costPerInputToken: 123,
costPerOutputToken: 123,
costPerCacheReadInputToken: 123,
cost: 123,
conversationSimulatorVersion: '<string>'
})
};
fetch('https://api.galtea.ai/inferenceResults', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.galtea.ai/inferenceResults",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sessionId' => 'session_123',
'sessionCustomId' => 'my-conversation-42',
'versionId' => 'ver_123',
'productId' => 'prod_123',
'userId' => 'user_123',
'index' => 0,
'error' => '<string>',
'input' => [
],
'actualOutput' => 'Model response text',
'retrievalContext' => 'Retrieved context document',
'latency' => 123,
'inputTokens' => 123,
'outputTokens' => 123,
'cacheReadInputTokens' => 123,
'tokens' => 123,
'costPerInputToken' => 123,
'costPerOutputToken' => 123,
'costPerCacheReadInputToken' => 123,
'cost' => 123,
'conversationSimulatorVersion' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.galtea.ai/inferenceResults"
payload := strings.NewReader("{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.galtea.ai/inferenceResults")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.galtea.ai/inferenceResults")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "ir_123",
"sessionId": "session_123",
"userId": "user_123",
"index": 0,
"status": "PENDING",
"error": null,
"input": {
"user_message": "User input text"
},
"actualOutput": "Model response",
"latency": 150,
"inputTokens": 100,
"outputTokens": 50,
"cacheReadInputTokens": 20,
"tokens": 150,
"costPerInputToken": 0.00001,
"costPerOutputToken": 0.00003,
"costPerCacheReadInputToken": 0.000005,
"cost": 0.001,
"creditsUsed": 1,
"droppedSpanCount": 2,
"conversationSimulatorVersion": "1.0.0",
"traceId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"createdAt": "2023-11-07T05:31:56Z",
"deletedAt": "2023-11-07T05:31:56Z",
"comments": [
{
"id": "comment_123",
"inferenceResultId": "inferenceResult_123",
"text": "Agent hallucinated the price.",
"tags": [
"hallucination",
"tone"
],
"userId": "user_123",
"userName": "John Doe",
"userEmail": "user@example.com",
"createdAt": "2023-11-07T05:31:56Z"
}
]
}{
"error": "Error type",
"message": "Error message description"
}Create trace
Create a new trace. Identify the session with exactly one of sessionId or sessionCustomId. With sessionCustomId (your own conversation id) an existing session with that custom id is found and appended to: provide either versionId or productId as the anchor (if both are given, versionId wins). The session must already exist — create it first through the sessions API with that custom_id. If no matching session exists, the call is rejected with a 400. See Traces. The REST path /inferenceResults and the inferenceResult* JSON fields keep the old name of this entity.
POST
/
inferenceResults
Create trace
curl --request POST \
--url https://api.galtea.ai/inferenceResults \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"sessionId": "session_123",
"sessionCustomId": "my-conversation-42",
"versionId": "ver_123",
"productId": "prod_123",
"userId": "user_123",
"index": 0,
"error": "<string>",
"input": {},
"actualOutput": "Model response text",
"retrievalContext": "Retrieved context document",
"latency": 123,
"inputTokens": 123,
"outputTokens": 123,
"cacheReadInputTokens": 123,
"tokens": 123,
"costPerInputToken": 123,
"costPerOutputToken": 123,
"costPerCacheReadInputToken": 123,
"cost": 123,
"conversationSimulatorVersion": "<string>"
}
'import requests
url = "https://api.galtea.ai/inferenceResults"
payload = {
"sessionId": "session_123",
"sessionCustomId": "my-conversation-42",
"versionId": "ver_123",
"productId": "prod_123",
"userId": "user_123",
"index": 0,
"error": "<string>",
"input": {},
"actualOutput": "Model response text",
"retrievalContext": "Retrieved context document",
"latency": 123,
"inputTokens": 123,
"outputTokens": 123,
"cacheReadInputTokens": 123,
"tokens": 123,
"costPerInputToken": 123,
"costPerOutputToken": 123,
"costPerCacheReadInputToken": 123,
"cost": 123,
"conversationSimulatorVersion": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sessionId: 'session_123',
sessionCustomId: 'my-conversation-42',
versionId: 'ver_123',
productId: 'prod_123',
userId: 'user_123',
index: 0,
error: '<string>',
input: {},
actualOutput: 'Model response text',
retrievalContext: 'Retrieved context document',
latency: 123,
inputTokens: 123,
outputTokens: 123,
cacheReadInputTokens: 123,
tokens: 123,
costPerInputToken: 123,
costPerOutputToken: 123,
costPerCacheReadInputToken: 123,
cost: 123,
conversationSimulatorVersion: '<string>'
})
};
fetch('https://api.galtea.ai/inferenceResults', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.galtea.ai/inferenceResults",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sessionId' => 'session_123',
'sessionCustomId' => 'my-conversation-42',
'versionId' => 'ver_123',
'productId' => 'prod_123',
'userId' => 'user_123',
'index' => 0,
'error' => '<string>',
'input' => [
],
'actualOutput' => 'Model response text',
'retrievalContext' => 'Retrieved context document',
'latency' => 123,
'inputTokens' => 123,
'outputTokens' => 123,
'cacheReadInputTokens' => 123,
'tokens' => 123,
'costPerInputToken' => 123,
'costPerOutputToken' => 123,
'costPerCacheReadInputToken' => 123,
'cost' => 123,
'conversationSimulatorVersion' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.galtea.ai/inferenceResults"
payload := strings.NewReader("{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.galtea.ai/inferenceResults")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.galtea.ai/inferenceResults")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sessionId\": \"session_123\",\n \"sessionCustomId\": \"my-conversation-42\",\n \"versionId\": \"ver_123\",\n \"productId\": \"prod_123\",\n \"userId\": \"user_123\",\n \"index\": 0,\n \"error\": \"<string>\",\n \"input\": {},\n \"actualOutput\": \"Model response text\",\n \"retrievalContext\": \"Retrieved context document\",\n \"latency\": 123,\n \"inputTokens\": 123,\n \"outputTokens\": 123,\n \"cacheReadInputTokens\": 123,\n \"tokens\": 123,\n \"costPerInputToken\": 123,\n \"costPerOutputToken\": 123,\n \"costPerCacheReadInputToken\": 123,\n \"cost\": 123,\n \"conversationSimulatorVersion\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "ir_123",
"sessionId": "session_123",
"userId": "user_123",
"index": 0,
"status": "PENDING",
"error": null,
"input": {
"user_message": "User input text"
},
"actualOutput": "Model response",
"latency": 150,
"inputTokens": 100,
"outputTokens": 50,
"cacheReadInputTokens": 20,
"tokens": 150,
"costPerInputToken": 0.00001,
"costPerOutputToken": 0.00003,
"costPerCacheReadInputToken": 0.000005,
"cost": 0.001,
"creditsUsed": 1,
"droppedSpanCount": 2,
"conversationSimulatorVersion": "1.0.0",
"traceId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"createdAt": "2023-11-07T05:31:56Z",
"deletedAt": "2023-11-07T05:31:56Z",
"comments": [
{
"id": "comment_123",
"inferenceResultId": "inferenceResult_123",
"text": "Agent hallucinated the price.",
"tags": [
"hallucination",
"tone"
],
"userId": "user_123",
"userName": "John Doe",
"userEmail": "user@example.com",
"createdAt": "2023-11-07T05:31:56Z"
}
]
}{
"error": "Error type",
"message": "Error message description"
}Authorizations
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-....
Body
application/json
ID of the session. Provide this or sessionCustomId.
Example:
"session_123"
Your own conversation id. An existing session with this custom id is found and appended to; if none matches the call returns a 400, so create the session first through the sessions API. Requires versionId or productId. Provide this or sessionId.
Example:
"my-conversation-42"
Version anchor for the sessionCustomId lookup. Provide this or productId; if both are given, versionId wins.
Example:
"ver_123"
Product anchor for the sessionCustomId lookup when no versionId is given: the existing session with that custom id is found across the product's versions.
Example:
"prod_123"
ID of the user
Example:
"user_123"
Index of the trace
Example:
0
Status of the trace
Available options:
PENDING, GENERATED, FAILED, SKIPPED Error message explaining why this trace failed or was skipped
Structured input data. For plain text, use { user_message: "..." }
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"
Retrieval context information
Example:
"Retrieved context document"
Latency in milliseconds
Number of input tokens
Number of output tokens
Number of cache read input tokens
Total number of tokens
Cost per input token
Cost per output token
Cost per cache read input token
Total cost
Version of the conversation simulator
Response
Trace created 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.
Example:
"ir_123"
Example:
"session_123"
Example:
"user_123"
Order index within the session
Example:
0
Available options:
PENDING, GENERATED, FAILED, SKIPPED Example:
"PENDING"
Error message explaining why this trace failed or was skipped
Example:
null
Structured input data. For plain text input, format is { user_message: "..." }
Example:
{ "user_message": "User input text" }
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"
Example:
150
Example:
100
Example:
50
Example:
20
Total tokens
Example:
150
Example:
0.00001
Example:
0.00003
Example:
0.000005
Example:
0.001
Example:
1
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
Example:
"1.0.0"
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"
Free-form reviewer annotations on this turn, oldest first.
Show child attributes
Show child attributes