Batch event ingestion endpoint for traces, spans, generations, scores, and more.

Ingestion API

The ingestion endpoint accepts batches of events for asynchronous processing. This is the primary endpoint used by the SDKs to send traces, spans, generations, scores, and other events.

Batch Ingestion

POST /api/public/ingestion

Authentication: Basic auth (public+secret) or Bearer write-only key.

Content-Type: application/json

Body size limit: 5 MB per request.

Request Body

{
  "batch": [
    {
      "id": "evt-uuid-1",
      "type": "trace-create",
      "timestamp": "2026-04-03T10:00:00.000Z",
      "body": {
        "id": "trace-uuid-1",
        "name": "my-pipeline",
        "userId": "user-123",
        "sessionId": "session-abc",
        "input": { "query": "What is AI?" },
        "output": { "answer": "AI is..." },
        "metadata": { "env": "production" },
        "tags": ["production", "v2"],
        "version": "2.0.0",
        "release": "2026-04-01"
      }
    },
    {
      "id": "evt-uuid-2",
      "type": "generation-create",
      "timestamp": "2026-04-03T10:00:01.000Z",
      "body": {
        "id": "gen-uuid-1",
        "traceId": "trace-uuid-1",
        "name": "llm-call",
        "model": "gpt-4o",
        "input": [{ "role": "user", "content": "What is AI?" }],
        "output": { "role": "assistant", "content": "AI is..." },
        "usage": { "input": 10, "output": 30, "total": 40 },
        "startTime": "2026-04-03T10:00:00.100Z",
        "endTime": "2026-04-03T10:00:01.000Z"
      }
    }
  ]
}

Event Types

`type`	Description
`trace-create`	Create or update a trace
`span-create`	Create a span observation
`generation-create`	Create a generation observation (LLM call)
`event-create`	Create a point-in-time event observation
`score-create`	Create an evaluation score
`observation-update`	Update an existing observation
`sdk-log`	Internal SDK log event

Trace Event Body Fields

Field	Type	Required	Description
`id`	`string`	No	Trace ID (auto-generated if omitted)
`name`	`string`	No	Trace name
`userId`	`string`	No	User identifier
`sessionId`	`string`	No	Session identifier
`input`	`any`	No	Trace input data
`output`	`any`	No	Trace output data
`metadata`	`object`	No	Arbitrary metadata
`tags`	`string[]`	No	String tags
`version`	`string`	No	Application version
`release`	`string`	No	Release identifier
`public`	`boolean`	No	Whether trace is public
`environment`	`string`	No	Environment name (default: `"default"`)

Generation Event Body Fields

Field	Type	Required	Description
`id`	`string`	No	Generation ID (auto-generated if omitted)
`traceId`	`string`	No	Parent trace ID
`parentObservationId`	`string`	No	Parent observation ID
`name`	`string`	No	Generation name
`model`	`string`	No	Model name (e.g., `"gpt-4o"`)
`modelParameters`	`object`	No	Model parameters (temperature, max_tokens, etc.)
`input`	`any`	No	Prompt / messages
`output`	`any`	No	Generated response
`usage`	`object`	No	Token counts: `{input, output, total}`
`startTime`	`ISO 8601`	No	Start timestamp
`endTime`	`ISO 8601`	No	End timestamp
`metadata`	`object`	No	Arbitrary metadata
`level`	`string`	No	`DEFAULT`, `DEBUG`, `WARNING`, `ERROR`
`version`	`string`	No	Version string

Response

{
  "successes": [
    { "id": "evt-uuid-1", "status": 201 },
    { "id": "evt-uuid-2", "status": 201 }
  ],
  "errors": []
}

cURL Example

curl -X POST https://evals-api.browserstack.com/api/public/ingestion \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "id": "evt-001",
        "type": "trace-create",
        "timestamp": "2026-04-03T10:00:00.000Z",
        "body": {
          "id": "trace-001",
          "name": "chat-request",
          "userId": "user-123",
          "input": { "message": "Hello" }
        }
      }
    ]
  }'

OpenTelemetry Ingestion

The platform accepts OTLP (OpenTelemetry Protocol) traces over HTTP:

POST /api/public/otel/v1/traces

Content-Type: application/x-protobuf

Authentication: Same Basic auth or Bearer write-only key.

# Using the OTel Collector or SDK with OTLP HTTP exporter:
# OTEL_EXPORTER_OTLP_ENDPOINT=https://evals-api.browserstack.com/api/public/otel
# OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64>"

The platform maps OTLP spans to its trace/observation model automatically.

Legacy Single-Event Endpoints

These endpoints create a single event per request (used by older SDK versions):

Method	Path	Description
`POST`	`/api/public/traces`	Create a single trace
`POST`	`/api/public/scores`	Create a single score
`POST`	`/api/public/generations`	Create a generation observation
`POST`	`/api/public/spans`	Create a span observation
`POST`	`/api/public/events`	Create an event observation

These accept the same body fields as the corresponding batch event bodies. All accept write-only keys.

Ingestion API

On this page