> ## 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 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](https://docs.galtea.ai/sdk/api/span/service). These endpoints serve spans, the steps inside a trace. Their REST path `/traces` keeps the old name of this entity. ## OpenAPI ````yaml https://api.galtea.ai/openapi.json post /traces/batch openapi: 3.0.0 info: version: 1.0.0 title: Product Management Service API description: API documentation for Product Management Service contact: name: Galtea AI servers: - url: https://api.galtea.ai security: - bearerAuth: [] tags: [] externalDocs: description: Galtea Platform Documentation url: https://docs.galtea.ai paths: /traces/batch: post: tags: - spans summary: Create spans batch description: >- 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](https://docs.galtea.ai/sdk/api/span/service). These endpoints serve spans, the steps inside a trace. Their REST path `/traces` keeps the old name of this entity. operationId: createTracesBatch parameters: - name: includeRejected in: query required: false description: >- Return the object response, which reports every refused span, instead of the bare array of created spans. schema: type: boolean default: false requestBody: required: true content: application/json: schema: type: object required: - traces properties: traces: type: array minItems: 1 description: The spans to create. items: type: object required: - inferenceResultId - name properties: id: type: string description: Optional custom span ID example: id_123 inferenceResultId: type: string description: ID of the trace this span belongs to example: ir_123 name: type: string description: Name of the span description: example: Example Name type: string nullable: true description: Optional description of the span type: type: string enum: - SPAN - GENERATION - EVENT - AGENT - TOOL - CHAIN - RETRIEVER - EVALUATOR - EMBEDDING - GUARDRAIL nullable: true description: >- Type of span. A value outside this list is not dropped, it is normalized to one of these types, and the original label is kept in the span's metadata under `galtea.span.original_type`. inputData: type: object nullable: true description: Input data for the span outputData: oneOf: - type: object - type: string nullable: true description: >- Output data from the span (an object, or a plain string) error: type: string nullable: true description: Error message if the span failed example: Error message latencyMs: type: number nullable: true description: Duration in milliseconds metadata: type: object nullable: true description: Additional span attributes parentTraceId: type: string nullable: true description: >- Parent span ID for hierarchical spans (references id of another span in batch) startTime: type: string format: date-time nullable: true description: Start time of the span endTime: type: string format: date-time nullable: true description: End time of the span responses: '200': description: >- At least one span was created. The default body is the bare array of created spans; with `includeRejected=true` it is the object form. content: application/json: schema: oneOf: - type: array description: Default body. The created spans. items: $ref: '#/components/schemas/Trace' - $ref: '#/components/schemas/CreateSpansBatchResult' '400': description: >- The request body carried no spans, or every span in it was dropped. A span naming an unknown trace is dropped like any other, so a single-span batch answers 400 here where `POST /traces` answers 404. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- One span belongs to a trace you cannot write to. This is the one refusal that costs the whole batch, so no span is created, unlike every other refusal, which is reported per span. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Trace: type: object description: >- 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. properties: id: type: string example: trace_123 inferenceResultId: type: string example: ir_123 name: type: string example: fetch_user_data type: type: string enum: - SPAN - GENERATION - EVENT - AGENT - TOOL - CHAIN - RETRIEVER - EVALUATOR - EMBEDDING - GUARDRAIL nullable: true example: TOOL description: type: string nullable: true example: Fetches user data from the database by ID description: Human-readable description of the operation. Maximum 1MB. inputData: type: object nullable: true example: user_id: '123' description: Input parameters passed to the operation outputData: oneOf: - type: object - type: string nullable: true example: name: John Doe email: john@example.com description: >- Result returned by the operation. Usually an object; a plain string for retrieval-context spans error: type: string nullable: true example: Connection timeout description: Error message if failed latencyMs: type: number nullable: true example: 45.5 description: Execution time in milliseconds metadata: type: object nullable: true example: model: gpt-4 temperature: 0.7 description: Additional custom metadata parentTraceId: type: string nullable: true example: trace_parent_123 description: ID of parent span for hierarchical relationships startTime: type: string format: date-time nullable: true endTime: type: string format: date-time nullable: true createdAt: type: string format: date-time deletedAt: type: string format: date-time nullable: true CreateSpansBatchResult: type: object description: >- Batch create result returned when `includeRejected=true`. `partialSuccess` is present only when at least one span was refused. required: - spans properties: spans: type: array description: The spans that were created. items: $ref: '#/components/schemas/Trace' partialSuccess: type: object required: - rejectedSpans - errors properties: rejectedSpans: type: integer example: 1 description: How many spans were refused. errors: type: array items: $ref: '#/components/schemas/RejectedSpan' Error: type: object properties: error: type: string example: Error type message: type: string example: Error message description RejectedSpan: type: object description: One span a batch create refused. Its siblings were still created. required: - index - name - reason properties: index: type: integer example: 2 description: >- Position of the span in the request array, so the caller can find it. name: type: string nullable: true example: fetch_user_data description: Name the span was sent with. Null when it carried no usable name. reason: type: string example: '"latencyMs" must be a non-negative number' description: Why the span was refused. securitySchemes: bearerAuth: type: http scheme: bearer description: >- 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-...`. ````