Create spans batch

Create multiple spans in a single API call. Partial success, not all-or-nothing: a span refused for a data problem (empty name, negative latency, oversize payload, unknown trace) does not stop its siblings, and its trace records how many of its spans were dropped. Set includeRejected=true to read which spans were refused. A span you are not allowed to write is the one exception and refuses the whole batch with a 403. See Spans. These endpoints serve spans, the steps inside a trace. Their REST path /traces keeps the old name of this entity.

POST /traces/batch

Create spans batch

cURL

curl --request POST \
  --url https://api.galtea.ai/traces/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "traces": [
    {
      "inferenceResultId": "ir_123",
      "name": "<string>",
      "id": "id_123",
      "description": "Example Name",
      "inputData": {},
      "outputData": {},
      "error": "Error message",
      "latencyMs": 123,
      "metadata": {},
      "parentTraceId": "<string>",
      "startTime": "2023-11-07T05:31:56Z",
      "endTime": "2023-11-07T05:31:56Z"
    }
  ]
}
'

200

[
  {
    "id": "trace_123",
    "inferenceResultId": "ir_123",
    "name": "fetch_user_data",
    "type": "TOOL",
    "description": "Fetches user data from the database by ID",
    "inputData": {
      "user_id": "123"
    },
    "outputData": {
      "name": "John Doe",
      "email": "[e-mail]"
    },
    "error": "Connection timeout",
    "latencyMs": 45.5,
    "metadata": {
      "model": "gpt-4",
      "temperature": 0.7
    },
    "parentTraceId": "trace_parent_123",
    "startTime": "2023-11-07T05:31:56Z",
    "endTime": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "deletedAt": "2023-11-07T05:31:56Z"
  }
]

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

Query Parameters

includeRejected · boolean · default: false

Return the object response, which reports every refused span, instead of the bare array of created spans.

Body

application/json

traces · object[] · required

The spans to create.

Minimum array length: 1

Show child attributes

Response

200

application/json

At least one span was created. The default body is the bare array of created spans; with includeRejected=true it is the object form.

object[]

object

A span: one step inside a trace, such as a tool call, a retrieval or an LLM call. The schema name and the /traces path still carry the old name of this entity, "trace". The parent trace is inferenceResultId; the parentTraceId field is the parent span, not the trace. Span ids start with trace_, so a trace_ id belongs here and never to a trace.

id · string

Example:

"trace_123"

inferenceResultId · string

Example:

"ir_123"

name · string

Example:

"fetch_user_data"

type · enum<string> | null

Available options: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL

Example:

"TOOL"

description · string | null

Human-readable description of the operation. Maximum 1MB.

Example:

"Fetches user data from the database by ID"

inputData · object | null

Input parameters passed to the operation

Example:

{ "user_id": "123" }

outputData · object string

Result returned by the operation. Usually an object; a plain string for retrieval-context spans

Example:

{
  "name": "John Doe",
  "email": "[e-mail]"
}

error · string | null

Error message if failed

Example:

"Connection timeout"

latencyMs · number | null

Execution time in milliseconds

Example:

45.5

metadata · object | null

Additional custom metadata

Example:

{ "model": "gpt-4", "temperature": 0.7 }

parentTraceId · string | null

ID of parent span for hierarchical relationships

Example:

"trace_parent_123"

startTime · string<date-time> | null

endTime · string<date-time> | null

createdAt · string<date-time>

deletedAt · string<date-time> | null