Skip to main content
POST
Create spans batch
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-....

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

Response

At least one span was created. The default body is the bare array of created spans; with includeRejected=true it is the object form. Each parentTraceId is the value the span was stored with: a span whose parent arrives in a concurrent request can be attached after this body is built, so read the span back to see the settled parent.

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:
outputData

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

Example:
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:
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
modelId
string | null
read-only

The model that answered this LLM call, matched by name when the span was ingested. Null when no live model of the organization, or global model, had the name the span reported. Deleting the model keeps it, so it can name a deleted model.

Example:

"model_123"

modelName
string | null
read-only

The model name the span reported, whether or not it matched a model.

Example:

"gpt-4o-mini"

inputTokens
integer | null
read-only

Input tokens the LLM call reported. Null without evaluation.readInference on the product.

Example:

100

outputTokens
integer | null
read-only

Output tokens the LLM call reported. Null without evaluation.readInference on the product.

Example:

50

cacheReadInputTokens
integer | null
read-only

Input tokens the LLM call read from the cache. Null without evaluation.readInference on the product.

Example:

20

tokens
integer | null
read-only

Sum of the input, output and cache-read tokens. Null without evaluation.readInference on the product.

Example:

170

costPerInputToken
number | null
read-only

Price of one input token, frozen at ingest from the model of this call, or from the version model when the span names no model. Null when the named model links to nothing or has no price. Null without evaluation.readInference on the product.

Example:

0.00001

costPerOutputToken
number | null
read-only

Price of one output token, frozen at ingest like costPerInputToken. Null without evaluation.readInference on the product.

Example:

0.00003

costPerCacheReadInputToken
number | null
read-only

Price of one cache-read token, frozen at ingest like costPerInputToken. Null without evaluation.readInference on the product.

Example:

0.000005

cost
number | null
read-only

Cost of this call at the frozen rates. Null when no rates were found. A turn's cost sums its spans' costs. Null without evaluation.readInference on the product.

Example:

0.0026