Annotation Queues

Create and manage annotation queues and their records for human labeling workflows using the Arize TypeScript SDK.

The annotation_queues functions are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.

List Annotation Queues

import { listAnnotationQueues } from "@arizeai/ax-client";

const { data: queues, pagination } = await listAnnotationQueues({
  space: "my-space",  // space name or ID (optional)
  name: "quality",    // substring filter on queue name (optional)
  limit: 10,
});

Create an Annotation Queue

import { createAnnotationQueue } from "@arizeai/ax-client";

const queue = await createAnnotationQueue({
  name: "Quality Review Queue",
  spaceId: "your_space_id",  // raw space ID required
  annotationConfigIds: ["your_annotation_config_id"],
  annotatorEmails: ["[e-mail]"],
  assignmentMethod: "all",  // "all" or "random" (optional, defaults to "all")
  instructions: "Review each span for accuracy and relevance.",  // optional
});

Get an Annotation Queue

import { getAnnotationQueue } from "@arizeai/ax-client";

// By ID
const queue = await getAnnotationQueue({ annotationQueue: "your_queue_id" });

// By name (requires space)
const queue = await getAnnotationQueue({
  annotationQueue: "Quality Review Queue",
  space: "my-space",
});

Update an Annotation Queue

import { updateAnnotationQueue } from "@arizeai/ax-client";

const queue = await updateAnnotationQueue({
  annotationQueue: "Quality Review Queue",  // queue name or ID
  space: "my-space",                        // required when using a name
  name: "Updated Queue Name",               // optional
  annotatorEmails: ["[e-mail]", "[e-mail]"],  // replaces all existing
});

Delete an Annotation Queue

import { deleteAnnotationQueue } from "@arizeai/ax-client";

await deleteAnnotationQueue({
  annotationQueue: "Quality Review Queue",  // queue name or ID
  space: "my-space",                        // required when using a name
});

Manage Records

List Records

import { listAnnotationQueueRecords } from "@arizeai/ax-client";

const { data: records, pagination } = await listAnnotationQueueRecords({
  annotationQueue: "your_queue_id",
  limit: 20,
});

Add Records

import { addAnnotationQueueRecords } from "@arizeai/ax-client";

const records = await addAnnotationQueueRecords({
  annotationQueue: "your_queue_id",
  recordSources: [
    {
      recordType: "span",
      projectId: "your_project_id",
      startTime: "2026-03-01T00:00:00Z",
      endTime: "2026-03-08T00:00:00Z",
      spanIds: ["your_span_id"],
    },
  ],
});

Annotate a Record

Submit annotations for a record. Annotations are upserted by annotation config name; omitted configs are left unchanged.

import { annotateAnnotationQueueRecord } from "@arizeai/ax-client";

const result = await annotateAnnotationQueueRecord({
  annotationQueue: "your_queue_id",
  annotationQueueRecordId: "your_record_id",
  annotations: [
    { name: "accuracy", label: "correct", score: 1.0 },
    { name: "quality", text: "Well-structured response" },
  ],
});

Assign a Record

Fully replaces the record-level user assignments. Pass an empty array to remove all assignments.

import { assignAnnotationQueueRecord } from "@arizeai/ax-client";

const result = await assignAnnotationQueueRecord({
  annotationQueue: "your_queue_id",
  annotationQueueRecordId: "your_record_id",
  assignedUserEmails: ["[e-mail]"],
});

Delete Records

import { deleteAnnotationQueueRecords } from "@arizeai/ax-client";

await deleteAnnotationQueueRecords({
  annotationQueue: "your_queue_id",
  recordIds: ["your_record_id_1", "your_record_id_2"],
});