Traces API

Traces represent a single end-to-end execution of your AI pipeline. Each trace can contain multiple observations (spans, generations, events).

List Traces

GET /api/public/traces

Returns a paginated list of traces for the current project.

Query Parameters

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`)
`limit`	`integer`	Items per page (default: `50`, max: `100`)
`name`	`string`	Filter by trace name
`userId`	`string`	Filter by user ID
`sessionId`	`string`	Filter by session ID
`tags`	`string \| string[]`	Filter by tags
`environment`	`string \| string[]`	Filter by environment
`version`	`string`	Filter by version
`release`	`string`	Filter by release
`fromTimestamp`	`ISO 8601`	Filter traces at or after this time
`toTimestamp`	`ISO 8601`	Filter traces at or before this time
`orderBy`	`string`	Sort: e.g., `timestamp.asc`, `timestamp.desc`

Response

{
  "data": [
    {
      "id": "trace-uuid-1",
      "externalId": null,
      "timestamp": "2026-04-03T10:00:00.000Z",
      "name": "rag-pipeline",
      "userId": "user-123",
      "sessionId": "session-abc",
      "metadata": { "env": "production" },
      "tags": ["production", "v2"],
      "release": "2026-04-01",
      "version": "2.0.0",
      "projectId": "proj-xyz",
      "environment": "production",
      "public": false,
      "bookmarked": false,
      "input": { "query": "What is quantum computing?" },
      "output": { "answer": "Quantum computing is..." },
      "observations": ["obs-uuid-1", "obs-uuid-2"],
      "scores": ["score-uuid-1"],
      "totalCost": 0.00042,
      "latency": 1523,
      "htmlPath": "/project/proj-xyz/traces/trace-uuid-1",
      "createdAt": "2026-04-03T10:00:00.000Z",
      "updatedAt": "2026-04-03T10:00:01.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 243,
    "totalPages": 5
  }
}

cURL Example

curl "https://evals-api.browserstack.com/api/public/traces?page=1&limit=10&userId=user-123" \
  -u "pk-lf-...:sk-lf-..."

Get Trace

GET /api/public/traces/{traceId}

Returns a single trace with all its observations and scores.

Path Parameters

Parameter	Type	Description
`traceId`	`string`	Trace ID

Response

{
  "id": "trace-uuid-1",
  "timestamp": "2026-04-03T10:00:00.000Z",
  "name": "rag-pipeline",
  "userId": "user-123",
  "sessionId": "session-abc",
  "metadata": { "env": "production" },
  "tags": ["production"],
  "projectId": "proj-xyz",
  "environment": "default",
  "public": false,
  "bookmarked": false,
  "input": { "query": "What is quantum computing?" },
  "output": { "answer": "Quantum computing is..." },
  "totalCost": 0.00042,
  "latency": 1523,
  "htmlPath": "/project/proj-xyz/traces/trace-uuid-1",
  "createdAt": "2026-04-03T10:00:00.000Z",
  "updatedAt": "2026-04-03T10:00:01.000Z",
  "observations": [
    {
      "id": "obs-uuid-1",
      "type": "GENERATION",
      "name": "llm-call",
      "model": "gpt-4o",
      "input": [{ "role": "user", "content": "What is quantum computing?" }],
      "output": { "role": "assistant", "content": "Quantum computing is..." },
      "usage": { "input": 20, "output": 80, "total": 100, "unit": "TOKENS" },
      "latency": 1400
    }
  ],
  "scores": [
    {
      "id": "score-uuid-1",
      "name": "correctness",
      "value": 0.9,
      "dataType": "NUMERIC",
      "source": "API"
    }
  ]
}

cURL Example

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

Create Trace

POST /api/public/traces

Creates a single trace. For bulk ingestion, prefer the batch ingestion endpoint.

Authentication: Accepts write-only keys.

Request Body

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	Input data
`output`	`any`	No	Output data
`metadata`	`object`	No	Arbitrary metadata
`tags`	`string[]`	No	Tags
`version`	`string`	No	Application version
`release`	`string`	No	Release identifier
`public`	`boolean`	No	Whether publicly accessible
`environment`	`string`	No	Environment name

Response

{ "id": "trace-uuid-1" }

cURL Example

curl -X POST https://evals-api.browserstack.com/api/public/traces \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rag-pipeline",
    "userId": "user-123",
    "sessionId": "session-abc",
    "input": { "query": "What is quantum computing?" },
    "tags": ["production"]
  }'

Delete Trace

DELETE /api/public/traces/{traceId}

Deletes a single trace and all its associated observations and scores.

Path Parameters

Parameter	Type	Description
`traceId`	`string`	Trace ID

Response

{ "message": "Traces deleted successfully" }

cURL Example

curl -X DELETE "https://evals-api.browserstack.com/api/public/traces/trace-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Bulk Delete Traces

DELETE /api/public/traces

Deletes multiple traces by ID in a single request.

Request Body

Field	Type	Required	Description
`traceIds`	`string[]`	Yes	List of trace IDs to delete (at least 1)

cURL Example

curl -X DELETE https://evals-api.browserstack.com/api/public/traces \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{ "traceIds": ["trace-uuid-1", "trace-uuid-2"] }'

Response

{ "message": "Traces deleted successfully" }

Traces API

On this page