> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Span Batch

> Create multiple spans in a single API call.

## Returns

Returns a list of the created [Span](/concepts/product/version/session/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](/concepts/product/version/session/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

```python theme={"system"}
galtea.spans.create_batch(
    [
        SpanBase(
            trace_id=trace_id,
            name="batch_span_1",
            type=SpanType.SPAN,
        )
    ]
)
```

## Parameters

<ResponseField name="spans" type="list[SpanBase]" required>
  List of span objects to create. Each span should include `trace_id`, `name`, and optionally other fields.
</ResponseField>

## 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](/concepts/product/version/session/span#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                                                                                                                                         |

<Note>
  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`.
</Note>