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"
    }
  ]
}
{
  "loc": [
    "<string>"
  ],
  "msg": "<string>",
  "type": "<string>"
}
{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}
{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}
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