Annotation Queues SDK Reference

Annotation Queues

List Annotation Queues

Returns annotation queues in the workspace, newest first.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.list(limit=10)

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.list({
    limit: 10,
  });

  console.log(result);
}

run();

Show Parameters

{
    "limit": Optional[int],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
    "search": Optional[str],
    "updated_by": Optional[str],
}

{
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
  search?: string;
  updatedBy?: string;
}

Show Response

{
    "object": str,
    "data": [{
        "id": str,
        "display_name": str,
        "description": str,
        "workspace_id": str,
        "project_id": Optional[str],
        "human_review_ids": List[str],
        "metadata": {
            "items_count": int,
        },
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,  # optional
        "updated": str,  # optional
    }],
    "has_more": bool,
}

{
  object: string;
  data: {
    id: string;
    displayName: string;
    description: string;
    workspaceId: string;
    projectId?: string;
    humanReviewIds: string[];
    metadata: {
      itemsCount: number;
    };
    createdById?: string;
    updatedById?: string;
    created?: Date;
    updated?: Date;
  }[];
  hasMore: boolean;
}

Create an Annotation Queue

Creates an annotation queue in a project.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.create(display_name="Weekly review queue", description="Items pending weekly annotation review", project_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.create({
    displayName: "Weekly review queue",
    description: "Items pending weekly annotation review",
    projectId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "display_name": str,  # required
    "description": str,  # required
    "project_id": str,  # required
}

{
  displayName: string;  // required
  description: string;  // required
  projectId: string;  // required
}

Show Response

{
    "id": str,
    "display_name": str,
    "description": str,
    "workspace_id": str,
    "project_id": Optional[str],
    "human_review_ids": List[str],
    "metadata": {
        "items_count": int,
    },
    "created_by_id": Optional[str],
    "updated_by_id": Optional[str],
    "created": str,  # optional
    "updated": str,  # optional
}

{
  id: string;
  displayName: string;
  description: string;
  workspaceId: string;
  projectId?: string;
  humanReviewIds: string[];
  metadata: {
    itemsCount: number;
  };
  createdById?: string;
  updatedById?: string;
  created?: Date;
  updated?: Date;
}

Retrieve an Annotation Queue

Retrieves an existing annotation queue by ID.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.retrieve(annotation_queue_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.retrieve({
    annotationQueueId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
}

{
  annotationQueueId: string;  // required
}

Show Response

{
    "id": str,
    "display_name": str,
    "description": str,
    "workspace_id": str,
    "project_id": Optional[str],
    "human_review_ids": List[str],
    "metadata": {
        "items_count": int,
    },
    "created_by_id": Optional[str],
    "updated_by_id": Optional[str],
    "created": str,  # optional
    "updated": str,  # optional
}

{
  id: string;
  displayName: string;
  description: string;
  workspaceId: string;
  projectId?: string;
  humanReviewIds: string[];
  metadata: {
    itemsCount: number;
  };
  createdById?: string;
  updatedById?: string;
  created?: Date;
  updated?: Date;
}

Delete an Annotation Queue

Deletes an annotation queue, its items, and the queue references stored on the annotated spans.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.annotation_queues.delete(annotation_queue_id="<id>")

    # Use the SDK ...

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.annotationQueues.delete({
    annotationQueueId: "<id>",
  });

}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
}

{
  annotationQueueId: string;  // required
}

Update an Annotation Queue

Partially updates an existing annotation queue. Setting project_id clears the legacy human_review_ids selection.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.update(annotation_queue_id="<id>", display_name="Weekly review queue")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.update({
    annotationQueueId: "<id>",
    updateAnnotationQueueRequest: {
      displayName: "Weekly review queue",
    },
  });

  console.log(result);
}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
    "display_name": Optional[str],
    "description": Optional[str],
    "project_id": Optional[str],
    "human_review_ids": List[str],  # optional
}

{
  annotationQueueId: string;  // required
  updateAnnotationQueueRequest: {  // required
    displayName?: string;
    description?: string;
    projectId?: string;
    humanReviewIds?: string[];
  };
}

Show Response

{
    "id": str,
    "display_name": str,
    "description": str,
    "workspace_id": str,
    "project_id": Optional[str],
    "human_review_ids": List[str],
    "metadata": {
        "items_count": int,
    },
    "created_by_id": Optional[str],
    "updated_by_id": Optional[str],
    "created": str,  # optional
    "updated": str,  # optional
}

{
  id: string;
  displayName: string;
  description: string;
  workspaceId: string;
  projectId?: string;
  humanReviewIds: string[];
  metadata: {
    itemsCount: number;
  };
  createdById?: string;
  updatedById?: string;
  created?: Date;
  updated?: Date;
}

Clear an Annotation Queue

Removes every item from the annotation queue without deleting the queue itself.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.annotation_queues.clear(annotation_queue_id="<id>")

    # Use the SDK ...

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.annotationQueues.clear({
    annotationQueueId: "<id>",
  });

}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
}

{
  annotationQueueId: string;  // required
}

List Annotation Queue Items

Queries items from the specified annotation queue. Items whose span no longer exists are skipped.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.list_items(annotation_queue_id="<id>", limit=10)

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.listItems({
    annotationQueueId: "<id>",
    limit: 10,
  });

  console.log(result);
}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
    "limit": Optional[int],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
}

{
  annotationQueueId: string;  // required
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
}

Show Response

{
    "object": str,
    "data": [{
        "id": str,
        "annotation_queue_id": str,
        "workspace_id": str,
        "used_human_review_ids": List[str],  # optional
        "type": str,
        "span_id": Optional[str],
        "trace_id": Optional[str],
        "datapoint_id": Optional[str],
    }],
    "has_more": bool,
}

{
  object: string;
  data: {
    id: string;
    annotationQueueId: string;
    workspaceId: string;
    usedHumanReviewIds?: string[];
    type: string;
    spanId?: string;
    traceId?: string;
    datapointId?: string;
  }[];
  hasMore: boolean;
}

Add Annotation Queue Items

Adds spans to the annotation queue. Spans already present are skipped; the response contains only the newly created items.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.add_items(annotation_queue_id="<id>", items=[
        {
            "span_id": "<id>",
            "trace_id": "<id>",
        },
    ])

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.addItems({
    annotationQueueId: "<id>",
    addAnnotationQueueItemsRequest: {
      items: [
        {
          spanId: "<id>",
          traceId: "<id>",
        },
      ],
    },
  });

  console.log(result);
}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
    "items": [{  # required
        "span_id": str,  # required
        "trace_id": str,  # required
    }],
}

{
  annotationQueueId: string;  // required
  addAnnotationQueueItemsRequest: {  // required
    items: {  // required
      spanId: string;  // required
      traceId: string;  // required
    }[];
  };
}

Remove Annotation Queue Items

Removes the referenced spans from the annotation queue.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    orq.annotation_queues.remove_items(annotation_queue_id="<id>", span_ids=[
        "<value 1>",
        "<value 2>",
    ])

    # Use the SDK ...

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  await orq.annotationQueues.removeItems({
    annotationQueueId: "<id>",
    removeAnnotationQueueItemsRequest: {
      spanIds: [
        "<value 1>",
        "<value 2>",
      ],
    },
  });

}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
    "span_ids": List[str],  # required
}

{
  annotationQueueId: string;  // required
  removeAnnotationQueueItemsRequest: {  // required
    spanIds: string[];  // required
  };
}

Retrieve an Annotation Queue Item

Retrieves an item from the specified annotation queue in its expanded form. An annotation queue item is a pointer to a span; this endpoint returns the fully resolved span the item references.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.annotation_queues.retrieve_item(annotation_queue_id="<id>", item_id="<id>")

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.annotationQueues.retrieveItem({
    annotationQueueId: "<id>",
    itemId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "annotation_queue_id": str,  # required
    "item_id": str,  # required
}

{
  annotationQueueId: string;  // required
  itemId: string;  // required
}

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs