Observations API

Observations are the individual steps within a trace: spans (arbitrary operations), generations (LLM calls), events (point-in-time logs), and tool calls.

List Observations

GET /api/public/observations

Returns a paginated list of observations across all traces.

Query Parameters

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`)
`limit`	`integer`	Items per page (default: `50`, max: `100`)
`type`	`string`	Filter by type: `GENERATION`, `SPAN`, `EVENT`, `TOOL_CALL`
`name`	`string`	Filter by observation name
`traceId`	`string`	Filter by parent trace ID
`userId`	`string`	Filter by user ID
`parentObservationId`	`string`	Filter by parent observation ID
`version`	`string`	Filter by version
`environment`	`string \| string[]`	Filter by environment
`fromStartTime`	`ISO 8601`	Filter observations starting at or after
`toStartTime`	`ISO 8601`	Filter observations starting at or before

Response

{
  "data": [
    {
      "id": "obs-uuid-1",
      "projectId": "proj-xyz",
      "traceId": "trace-uuid-1",
      "parentObservationId": null,
      "name": "llm-call",
      "type": "GENERATION",
      "environment": "production",
      "startTime": "2026-04-03T10:00:00.100Z",
      "endTime": "2026-04-03T10:00:01.100Z",
      "version": "2.0.0",
      "createdAt": "2026-04-03T10:00:01.200Z",
      "updatedAt": "2026-04-03T10:00:01.200Z",
      "input": [{ "role": "user", "content": "Explain quantum computing." }],
      "output": { "role": "assistant", "content": "Quantum computing..." },
      "metadata": null,
      "level": "DEFAULT",
      "statusMessage": null,
      "model": "gpt-4o",
      "modelParameters": { "temperature": 0.7 },
      "completionStartTime": "2026-04-03T10:00:00.500Z",
      "promptId": null,
      "promptName": null,
      "promptVersion": null,
      "usageDetails": { "input": 30, "output": 90, "total": 120 },
      "costDetails": { "input": 0.00009, "output": 0.00027, "total": 0.00036 },
      "usage": { "unit": "TOKENS", "input": 30, "output": 90, "total": 120 },
      "unit": "TOKENS",
      "promptTokens": 30,
      "completionTokens": 90,
      "totalTokens": 120,
      "modelId": "model-uuid-1",
      "inputPrice": 0.000003,
      "outputPrice": 0.000003,
      "totalPrice": 0.000012,
      "calculatedInputCost": 0.00009,
      "calculatedOutputCost": 0.00027,
      "calculatedTotalCost": 0.00036,
      "latency": 1000,
      "timeToFirstToken": 400
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 10,
    "totalPages": 1
  }
}

cURL Example

curl "https://evals-api.browserstack.com/api/public/observations?traceId=trace-uuid-1&type=GENERATION" \
  -u "pk-lf-...:sk-lf-..."

Get Observation

GET /api/public/observations/{observationId}

Returns a single observation by ID.

Path Parameters

Parameter	Type	Description
`observationId`	`string`	Observation ID

Response

Same schema as the list response items.

cURL Example

curl "https://evals-api.browserstack.com/api/public/observations/obs-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Observation Types

Type	Description
`GENERATION`	An LLM API call. Includes `model`, `modelParameters`, token usage, and cost fields.
`SPAN`	A generic operation with a duration (start/end time).
`EVENT`	A point-in-time log without a duration.
`TOOL_CALL`	A tool/function call invocation.

Observation Fields

Field	Type	Description
`id`	`string`	Observation ID
`traceId`	`string \| null`	Parent trace ID
`parentObservationId`	`string \| null`	Parent observation ID (for nesting)
`name`	`string \| null`	Observation name
`type`	`string`	`GENERATION`, `SPAN`, `EVENT`, `TOOL_CALL`
`startTime`	`ISO 8601`	Start time
`endTime`	`ISO 8601 \| null`	End time
`input`	`any`	Input data
`output`	`any`	Output data
`metadata`	`any`	Metadata
`level`	`string`	`DEFAULT`, `DEBUG`, `WARNING`, `ERROR`
`model`	`string \| null`	Model name (GENERATION only)
`modelParameters`	`object \| null`	Model parameters (GENERATION only)
`usage`	`object`	Token usage: `{input, output, total, unit}`
`usageDetails`	`object`	Detailed usage breakdown
`calculatedTotalCost`	`number \| null`	Calculated cost in USD
`latency`	`number \| null`	Duration in milliseconds
`timeToFirstToken`	`number \| null`	Time to first token in ms (GENERATION only)

Creating Observations

Observations are created via the Ingestion API using event types span-create, generation-create, and event-create. Use the batch endpoint for SDK-level usage.

Observations API

On this page