Sessions API

Sessions group related traces from a single user interaction or conversation. A session is automatically created when a trace is ingested with a sessionId.

List Sessions

GET /api/public/sessions

Query Parameters

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`)
`limit`	`integer`	Items per page (default: `50`)
`fromTimestamp`	`ISO 8601`	Filter sessions created at or after
`toTimestamp`	`ISO 8601`	Filter sessions created at or before
`environment`	`string \| string[]`	Filter by environment

Response

{
  "data": [
    {
      "id": "session-abc",
      "createdAt": "2026-04-03T10:00:00.000Z",
      "projectId": "proj-xyz",
      "environment": "production"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 12,
    "totalPages": 1
  }
}

cURL Example

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

Get Session

GET /api/public/sessions/{sessionId}

Returns a session along with all traces belonging to it.

Path Parameters

Parameter	Type	Description
`sessionId`	`string`	Session ID

Response

{
  "id": "session-abc",
  "createdAt": "2026-04-03T10:00:00.000Z",
  "projectId": "proj-xyz",
  "environment": "production",
  "traces": [
    {
      "id": "trace-uuid-1",
      "timestamp": "2026-04-03T10:00:00.000Z",
      "name": "rag-pipeline",
      "userId": "user-123",
      "sessionId": "session-abc",
      "metadata": null,
      "tags": [],
      "release": null,
      "version": null,
      "projectId": "proj-xyz",
      "environment": "production",
      "public": false,
      "bookmarked": false,
      "input": { "query": "What is quantum computing?" },
      "output": null,
      "createdAt": "2026-04-03T10:00:00.000Z",
      "updatedAt": "2026-04-03T10:00:01.000Z"
    }
  ]
}

cURL Example

curl "https://evals-api.browserstack.com/api/public/sessions/session-abc" \
  -u "pk-lf-...:sk-lf-..."

Session Fields

Field	Type	Description
`id`	`string`	Session ID (set by you when creating traces)
`createdAt`	`ISO 8601`	When the session was first seen
`projectId`	`string`	Project this session belongs to
`environment`	`string`	Environment name

Creating Sessions

Sessions are implicitly created when you ingest a trace with a sessionId. There is no separate "create session" endpoint — pass sessionId in your trace body:

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-uuid-1",
          "name": "chat-turn-1",
          "sessionId": "session-abc",
          "userId": "user-123"
        }
      }
    ]
  }'

Sessions API

On this page