Create Span Batch

Create multiple spans in a single API call.

Returns

Returns a list of the created Span objects.

The call is a partial success, not all-or-nothing. The API creates every valid span and drops only the ones with a data problem, such as an empty name, a negative latency, an oversize payload, or an unknown trace. So the returned list can be shorter than the list you sent. The SDK logs one warning that names each dropped span by its position in your list, with the reason. Each drop is also counted on the span’s trace, so the dashboard shows it too. If the API drops every span in the call, it returns a 400 error instead.

One case is not a partial success: a span belonging to a trace you are not allowed to write returns a 403 and creates nothing at all.

Example

galtea.spans.create_batch(
    [
        SpanBase(
            trace_id=trace_id,
            name="batch_span_1",
            type=SpanType.SPAN,
        )
    ]
)

Parameters

spans · list[SpanBase] · required

List of span objects to create. Each span should include trace_id, name, and optionally other fields.

SpanBase Fields

Field	Type	Required	Description
trace_id	str	Yes	ID of the trace this span belongs to
name	str	Yes	Name of the traced operation
id	str	No	Client-generated ID (auto-generated if not provided)
type	SpanType	No	Type: SPAN, GENERATION, EVENT, AGENT, TOOL, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL. See Span Types
parent_trace_id	str	No	ID of parent span
input_data	dict	No	Input parameters
output_data	dict	No	Output result
error	str	No	Error message if failed
latency_ms	float	No	Execution time in milliseconds
start_time	str	No	ISO 8601 timestamp when the span started
end_time	str	No	ISO 8601 timestamp when the span ended
metadata	dict	No	Additional custom metadata

For type, other string values are sent to the API unchanged. The API never drops a span for an unrecognized type. It normalizes the value to a known span type and keeps your original label in the span’s metadata, under the key galtea.span.original_type.