Skip to main content
POST
/
spans-bulk
curl --request POST \
  --url https://api.promptlayer.com/spans-bulk \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "spans": [
    {
      "name": "llm_call",
      "context": {
        "trace_id": "d4b5e2a13c8f4e9ab7d61a2b3c4d5e6f",
        "span_id": "a1b2c3d45e6f7a8b",
        "trace_state": "promptlayer=enabled"
      },
      "kind": "SpanKind.CLIENT",
      "parent_id": "parent123",
      "start_time": 1630000000000000000,
      "end_time": 1630000001000000000,
      "status": {
        "status_code": "StatusCode.OK",
        "description": "Success"
      },
      "attributes": {
        "llm.provider": "openai",
        "llm.model": "gpt-3.5-turbo"
      },
      "resource": {
        "attributes": {
          "service.name": "my-app"
        },
        "schema_url": "https://opentelemetry.io/schemas/1.9.0"
      },
      "log_request": {
        "provider": "openai",
        "model": "gpt-3.5-turbo",
        "input": {
          "type": "chat",
          "messages": [
            {
              "role": "user",
              "content": [
                {
                  "type": "text",
                  "text": "Hello!"
                }
              ]
            }
          ]
        },
        "output": {
          "type": "chat",
          "messages": [
            {
              "role": "assistant",
              "content": [
                {
                  "type": "text",
                  "text": "Hi there! How can I help you?"
                }
              ]
            }
          ]
        },
        "request_start_time": "2024-01-20T10:00:00Z",
        "request_end_time": "2024-01-20T10:00:01Z",
        "prompt_name": "greeting_prompt",
        "prompt_version_number": 1,
        "input_tokens": 10,
        "output_tokens": 12,
        "tags": [
          "production",
          "greeting"
        ],
        "metadata": {
          "user_id": "user123",
          "session": "abc123"
        }
      }
    }
  ]
}
'
{
  "success": true,
  "spans": [
    {
      "id": 101,
      "name": "llm_call",
      "span_id": "a1b2c3d45e6f7a8b"
    }
  ],
  "request_logs": [
    {
      "id": 12345,
      "span_id": "a1b2c3d45e6f7a8b"
    }
  ]
}
Create multiple observability spans in one request, optionally creating a request log alongside each span. Use this endpoint when ingesting telemetry data that is not already sent through OTLP.

​
Behavior Notes

  • When log_request is provided, the created request log is associated with the span by span_id.
  • If request_start_time or request_end_time is omitted from log_request, PromptLayer inherits the value from the parent span.
  • If a referenced prompt is not found, the span is still created but the request log creation for that span is skipped.
  • Bulk span creation is atomic; if any span creation fails, the entire batch is rolled back.

Authorizations

​
X-API-KEY
string
header
required

Body

application/json

Create multiple observability spans in a single request. Each span may include log_request to create an associated request log.

​
spans
Span · object[]
required
​
close_after
boolean
default:false

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

Successful Response

​
success
boolean
required
​
spans
Spans · object[]
required
​
request_logs
Request Logs · object[] | null
​
rejected_span_ids
string[] | null

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[] | null

Trace IDs that were closed and caused span rejections. Only present when one or more spans were rejected.

​
rejection_reason
enum<string> | null

The reason spans were rejected. Currently only trace_closed is possible. Only present when one or more spans were rejected.

Available options:
trace_closed