Update trace

curl --request PATCH \
  --url https://api.galtea.ai/inferenceResults/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actualOutput": "Model response text",
  "retrievalContext": "Retrieved context document",
  "error": "<string>",
  "latency": 123,
  "input": "<string>",
  "inputTokens": 123,
  "outputTokens": 123,
  "cacheReadInputTokens": 123,
  "tokens": 123,
  "cost": 123,
  "costPerInputToken": 123,
  "costPerOutputToken": 123,
  "costPerCacheReadInputToken": 123,
  "conversationSimulatorVersion": "<string>"
}
'

import requests

url = "https://api.galtea.ai/inferenceResults/{id}"

payload = {
    "actualOutput": "Model response text",
    "retrievalContext": "Retrieved context document",
    "error": "<string>",
    "latency": 123,
    "input": "<string>",
    "inputTokens": 123,
    "outputTokens": 123,
    "cacheReadInputTokens": 123,
    "tokens": 123,
    "cost": 123,
    "costPerInputToken": 123,
    "costPerOutputToken": 123,
    "costPerCacheReadInputToken": 123,
    "conversationSimulatorVersion": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    actualOutput: 'Model response text',
    retrievalContext: 'Retrieved context document',
    error: '<string>',
    latency: 123,
    input: '<string>',
    inputTokens: 123,
    outputTokens: 123,
    cacheReadInputTokens: 123,
    tokens: 123,
    cost: 123,
    costPerInputToken: 123,
    costPerOutputToken: 123,
    costPerCacheReadInputToken: 123,
    conversationSimulatorVersion: '<string>'
  })
};

fetch('https://api.galtea.ai/inferenceResults/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'actualOutput' => 'Model response text',
    'retrievalContext' => 'Retrieved context document',
    'error' => '<string>',
    'latency' => 123,
    'input' => '<string>',
    'inputTokens' => 123,
    'outputTokens' => 123,
    'cacheReadInputTokens' => 123,
    'tokens' => 123,
    'cost' => 123,
    'costPerInputToken' => 123,
    'costPerOutputToken' => 123,
    'costPerCacheReadInputToken' => 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/{id}"

	payload := strings.NewReader("{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 123,\n  \"conversationSimulatorVersion\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.galtea.ai/inferenceResults/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 123,\n  \"conversationSimulatorVersion\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.galtea.ai/inferenceResults/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 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"
}

{
  "error": "Error type",
  "message": "Error message description"
}

PATCH

inferenceResults

{id}

Update trace

curl --request PATCH \
  --url https://api.galtea.ai/inferenceResults/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "actualOutput": "Model response text",
  "retrievalContext": "Retrieved context document",
  "error": "<string>",
  "latency": 123,
  "input": "<string>",
  "inputTokens": 123,
  "outputTokens": 123,
  "cacheReadInputTokens": 123,
  "tokens": 123,
  "cost": 123,
  "costPerInputToken": 123,
  "costPerOutputToken": 123,
  "costPerCacheReadInputToken": 123,
  "conversationSimulatorVersion": "<string>"
}
'

import requests

url = "https://api.galtea.ai/inferenceResults/{id}"

payload = {
    "actualOutput": "Model response text",
    "retrievalContext": "Retrieved context document",
    "error": "<string>",
    "latency": 123,
    "input": "<string>",
    "inputTokens": 123,
    "outputTokens": 123,
    "cacheReadInputTokens": 123,
    "tokens": 123,
    "cost": 123,
    "costPerInputToken": 123,
    "costPerOutputToken": 123,
    "costPerCacheReadInputToken": 123,
    "conversationSimulatorVersion": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    actualOutput: 'Model response text',
    retrievalContext: 'Retrieved context document',
    error: '<string>',
    latency: 123,
    input: '<string>',
    inputTokens: 123,
    outputTokens: 123,
    cacheReadInputTokens: 123,
    tokens: 123,
    cost: 123,
    costPerInputToken: 123,
    costPerOutputToken: 123,
    costPerCacheReadInputToken: 123,
    conversationSimulatorVersion: '<string>'
  })
};

fetch('https://api.galtea.ai/inferenceResults/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'actualOutput' => 'Model response text',
    'retrievalContext' => 'Retrieved context document',
    'error' => '<string>',
    'latency' => 123,
    'input' => '<string>',
    'inputTokens' => 123,
    'outputTokens' => 123,
    'cacheReadInputTokens' => 123,
    'tokens' => 123,
    'cost' => 123,
    'costPerInputToken' => 123,
    'costPerOutputToken' => 123,
    'costPerCacheReadInputToken' => 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/{id}"

	payload := strings.NewReader("{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 123,\n  \"conversationSimulatorVersion\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", 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.patch("https://api.galtea.ai/inferenceResults/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 123,\n  \"conversationSimulatorVersion\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.galtea.ai/inferenceResults/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"actualOutput\": \"Model response text\",\n  \"retrievalContext\": \"Retrieved context document\",\n  \"error\": \"<string>\",\n  \"latency\": 123,\n  \"input\": \"<string>\",\n  \"inputTokens\": 123,\n  \"outputTokens\": 123,\n  \"cacheReadInputTokens\": 123,\n  \"tokens\": 123,\n  \"cost\": 123,\n  \"costPerInputToken\": 123,\n  \"costPerOutputToken\": 123,\n  \"costPerCacheReadInputToken\": 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"
}

{
  "error": "Error type",
  "message": "Error message description"
}

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

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 needs a non-empty uri; an answer that is only a file needs no scalar.

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

input

Agent input for this turn. Plain text by default; for voice, an envelope carrying audio content parts.

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 whenever the request carries an input and omits this.

outputTokens

integer

Output tokens generated by the model. Recounted from the output whenever the request carries an output and omits this.

cacheReadInputTokens

integer

Input tokens read from the model cache

tokens

integer

Total tokens. A value you send here is stored as sent. Omitted, it is re-derived from the three counts above whenever this row carries any of them.

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 whenever this row carries both.

costPerInputToken

number

costPerOutputToken

number

costPerCacheReadInputToken

number

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.

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) beside an optional user_message is stored as sent: nothing inside it is checked or filled, and the judge reads only the text beside the parts.

Example:

{ "user_message": "User input text" }

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.

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 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.

Show child attributes

API Reference

api-tokens

auth

organizations

user-groups

metrics

specifications

models

products

versions

monitors

endpoint-connections

datasets

test-cases

sessions

traces

spans

analytics

storage

evaluator-models

jobs

otel

phone-connections

web-rtc-connections

evaluations

comments

runs

Update trace

Authorizations

Path Parameters

Body

Response