Annotation Queues API

Annotation queues enable human reviewers to score and label traces. You can create queues, add items from traces, and track review progress programmatically.

List Annotation Queues

GET /api/public/annotation-queues

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`)
`limit`	`integer`	Items per page (default: `50`)

curl "https://evals-api.browserstack.com/api/public/annotation-queues" \
  -u "pk-lf-...:sk-lf-..."

Response:

{
  "data": [
    {
      "id": "queue-uuid-1",
      "name": "Production Review",
      "description": "Review production traces for quality",
      "scoreConfigIds": ["config-uuid-1", "config-uuid-2"],
      "createdAt": "2026-04-03T10:00:00.000Z",
      "updatedAt": "2026-04-03T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 3,
    "totalPages": 1
  }
}

Get Annotation Queue

GET /api/public/annotation-queues/{queueId}

curl "https://evals-api.browserstack.com/api/public/annotation-queues/queue-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Response:

{
  "id": "queue-uuid-1",
  "name": "Production Review",
  "description": "Review production traces for quality",
  "scoreConfigIds": ["config-uuid-1"],
  "createdAt": "2026-04-03T10:00:00.000Z",
  "updatedAt": "2026-04-03T10:00:00.000Z"
}

Create Annotation Queue

POST /api/public/annotation-queues

Field	Type	Required	Description
`name`	`string`	Yes	Queue name
`description`	`string`	No	Description
`scoreConfigIds`	`string[]`	No	Score config IDs for this queue

curl -X POST https://evals-api.browserstack.com/api/public/annotation-queues \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Review",
    "description": "Review production traces",
    "scoreConfigIds": ["config-uuid-1"]
  }'

Delete Annotation Queue

DELETE /api/public/annotation-queues/{queueId}

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

Queue Items

Queue items are the individual traces or observations assigned for review.

List Queue Items

GET /api/public/annotation-queues/{queueId}/items

Parameter	Type	Description
`page`	`integer`	Page number
`limit`	`integer`	Items per page
`status`	`string`	Filter by status: `PENDING`, `ACTIVE`, `DONE`, `SKIPPED`
`runIds`	`string \| string[]`	Filter by run IDs

curl "https://evals-api.browserstack.com/api/public/annotation-queues/queue-uuid-1/items?status=PENDING" \
  -u "pk-lf-...:sk-lf-..."

Response:

{
  "data": [
    {
      "id": "item-uuid-1",
      "queueId": "queue-uuid-1",
      "objectId": "trace-uuid-1",
      "objectType": "TRACE",
      "status": "PENDING",
      "completedAt": null,
      "createdAt": "2026-04-03T10:00:00.000Z",
      "updatedAt": "2026-04-03T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 5,
    "totalPages": 1
  }
}

Get Queue Item

GET /api/public/annotation-queues/{queueId}/items/{itemId}

curl "https://evals-api.browserstack.com/api/public/annotation-queues/queue-uuid-1/items/item-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Create Queue Item

POST /api/public/annotation-queues/{queueId}/items

Field	Type	Required	Description
`objectId`	`string`	Yes	ID of the trace or observation
`objectType`	`string`	Yes	`TRACE` or `OBSERVATION`

curl -X POST "https://evals-api.browserstack.com/api/public/annotation-queues/queue-uuid-1/items" \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "objectId": "trace-uuid-1",
    "objectType": "TRACE"
  }'

Delete Queue Item

DELETE /api/public/annotation-queues/{queueId}/items/{itemId}

curl -X DELETE "https://evals-api.browserstack.com/api/public/annotation-queues/queue-uuid-1/items/item-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Item Status Values

Status	Description
`PENDING`	Waiting for review
`ACTIVE`	Currently being reviewed
`DONE`	Review complete
`SKIPPED`	Reviewer skipped this item

Object Types

`objectType`	Description
`TRACE`	The item references a trace
`OBSERVATION`	The item references a specific observation

Annotation Queues API

On this page