---
title: "Create Spans Bulk"
method: POST
path: "/spans-bulk"
tags: ["spans"]
---

# Create Spans Bulk

`POST /spans-bulk`

## Request body

- CreateSpansBulk — Create multiple observability spans in a single request. Each span may include log_request to create an associated request log.
  - `spans` Span[], required
    - `name` string, required
    - `context` SpanContext, required
      - `trace_id` string, required
      - `span_id` string, required
      - `trace_state` string, required
    - `kind` 'SpanKind.CLIENT' | 'SpanKind.CONSUMER' | 'SpanKind.INTERNAL' | 'SpanKind.PRODUCER' | 'SpanKind.SERVER', required
    - `parent_id` string, nullable
    - `start_time` integer, required
    - `end_time` integer, required
    - `status` SpanStatus, required
      - `status_code` 'StatusCode.ERROR' | 'StatusCode.OK' | 'StatusCode.UNSET', required
      - `description` string, nullable
    - `attributes` object, required
    - `events` object[]
    - `links` object[]
    - `resource` SpanResource, required
      - `attributes` object, required
      - `schema_url` string, required
    - `log_request` LogRequest — Request body for custom logging. Chat message content must be an array of content blocks, not a plain string.
      - `provider` string, required
      - `model` string, required
      - `input` union, required
        - CompletionPrompt
          - `content` union[], required
            - union
              - …
          - `input_variables` string[]
          - `template_format` 'f-string' | 'jinja2'
          - `type` 'completion'
        - ChatPrompt
          - `messages` union[], required
            - union
              - …
          - `functions` Function[], nullable
            - `name` string, required
            - `description` string
            - `strict` boolean — Whether to enable strict schema validation for the function parameters.
            - `parameters` object
          - `tools` Tool[], nullable
            - union
              - …
          - `function_call` union
            - string
            - MessageFunctionCall
              - …
          - `tool_choice` union
            - string
            - ChatToolChoice
              - …
          - `type` 'chat'
          - `input_variables` string[]
      - `output` union, required
        - CompletionPrompt
          - `content` union[], required
            - union
              - …
          - `input_variables` string[]
          - `template_format` 'f-string' | 'jinja2'
          - `type` 'completion'
        - ChatPrompt
          - `messages` union[], required
            - union
              - …
          - `functions` Function[], nullable
            - `name` string, required
            - `description` string
            - `strict` boolean — Whether to enable strict schema validation for the function parameters.
            - `parameters` object
          - `tools` Tool[], nullable
            - union
              - …
          - `function_call` union
            - string
            - MessageFunctionCall
              - …
          - `tool_choice` union
            - string
            - ChatToolChoice
              - …
          - `type` 'chat'
          - `input_variables` string[]
      - `request_start_time` string, date-time, required
      - `request_end_time` string, date-time, required
      - `parameters` object — Model parameters including temperature, max_tokens, etc. Can also include structured output configuration via response_format.json_schema. See documentation for structured output examples.
      - `tags` string[]
      - `metadata` object — Custom key-value pairs for tracking additional request information. Keys are limited to 1024 characters.
      - `prompt_name` string, nullable
      - `prompt_id` integer, nullable — The ID of the prompt template used for this request. This is useful for tracking which prompt was used in the request.
      - `prompt_version_number` integer, nullable
      - `prompt_input_variables` object
      - `input_tokens` integer
      - `output_tokens` integer
      - `price` number
      - `function_name` string
      - `score` integer
      - `api_type` string, nullable
      - `status` 'SUCCESS' | 'WARNING' | 'ERROR' — Request status. | Value | Description | |-------|-------------| | `SUCCESS` | Request completed successfully (default) | | `WARNING` | Request succeeded but had issues (e.g., retries, degraded response) | | `ERROR` | Request failed |
      - `error_type` 'PROVIDER_TIMEOUT' | 'PROVIDER_QUOTA_LIMIT' | 'PROVIDER_RATE_LIMIT' | 'PROVIDER_PARTIAL_RESPONSE' | 'PROVIDER_AUTH_ERROR' | 'PROVIDER_ERROR' | 'TEMPLATE_RENDER_ERROR' | 'VARIABLE_MISSING_OR_EMPTY' | 'UNKNOWN_ERROR', nullable — Categorized error type. | Value | Description | Allowed Statuses | |-------|-------------|------------------| | `PROVIDER_RATE_LIMIT` | Rate limit hit on provider API | WARNING, ERROR | | `PROVIDER_QUOTA_LIMIT` | Account quota or spending limit exceeded | WARNING, ERROR | | `PROVIDER_PARTIAL_RESPONSE` | Provider returned a successful response, but the saved output may be incomplete, filtered, blocked, malformed, or otherwise partial | WARNING | | `VARIABLE_MISSING_OR_EMPTY` | Required template variable was missing or empty | WARNING | | `PROVIDER_TIMEOUT` | Request timed out | ERROR | | `PROVIDER_AUTH_ERROR` | Authentication failed with provider | ERROR | | `PROVIDER_ERROR` | General provider-side error | ERROR | | `TEMPLATE_RENDER_ERROR` | Failed to render prompt template | ERROR | | `UNKNOWN_ERROR` | Uncategorized error | WARNING, ERROR |
      - `error_message` string, nullable — Detailed error message describing what went wrong. Maximum 1024 characters.
  - `close_after` boolean — When true, all trace IDs in this batch are marked as closed after the spans are persisted. Subsequent span writes for those traces will be rejected with a trace_closed rejection reason. Defaults to false.

## Response `201`

Successful Response

- CreateSpansBulkResponse
  - `success` boolean, required
  - `spans` object[], required
  - `request_logs` object[], nullable
  - `rejected_span_ids` string[], nullable — Span IDs that were dropped because they belong to a closed trace. Only present when one or more spans were rejected.
  - `rejected_trace_ids` string[], nullable — Trace IDs that were closed and caused span rejections. Only present when one or more spans were rejected.
  - `rejection_reason` 'trace_closed', nullable — The reason spans were rejected. Currently only `trace_closed` is possible. Only present when one or more spans were rejected.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - missing or invalid API key.
- `403` — Forbidden - API key does not have access to the requested resource.
- `422` — Validation error - request parameters or body are invalid.
- `500` — Internal Server Error

---

[API](https://skmtc.dev/promptlayer/apis/promptlayer-api.md) · [All operations](https://skmtc.dev/promptlayer/apis/promptlayer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/promptlayer/promptlayer-api/revisions/a23093a0a506/schema)