> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotation Queues SDK Reference

> Manage annotation queues with the Node.js and Python SDKs: create, update, and clear queues and add, remove, or retrieve span items for review.

## Annotation Queues

### List Annotation Queues

Returns annotation queues in the workspace, newest first.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "search": Optional[str],
        "updated_by": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      search?: string;
      updatedBy?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      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;
    }
    ```
  </CodeGroup>
</Expandable>

### Create an Annotation Queue

Creates an annotation queue in a project.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "display_name": str,  # required
        "description": str,  # required
        "project_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      displayName: string;  // required
      description: string;  // required
      projectId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      description: string;
      workspaceId: string;
      projectId?: string;
      humanReviewIds: string[];
      metadata: {
        itemsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve an Annotation Queue

Retrieves an existing annotation queue by ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      description: string;
      workspaceId: string;
      projectId?: string;
      humanReviewIds: string[];
      metadata: {
        itemsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an Annotation Queue

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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 ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update an Annotation Queue

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "project_id": Optional[str],
        "human_review_ids": List[str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
      updateAnnotationQueueRequest: {  // required
        displayName?: string;
        description?: string;
        projectId?: string;
        humanReviewIds?: string[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      displayName: string;
      description: string;
      workspaceId: string;
      projectId?: string;
      humanReviewIds: string[];
      metadata: {
        itemsCount: number;
      };
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Clear an Annotation Queue

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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 ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### List Annotation Queue Items

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        annotationQueueId: string;
        workspaceId: string;
        usedHumanReviewIds?: string[];
        type: string;
        spanId?: string;
        traceId?: string;
        datapointId?: string;
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Add Annotation Queue Items

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
        "items": [{  # required
            "span_id": str,  # required
            "trace_id": str,  # required
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
      addAnnotationQueueItemsRequest: {  // required
        items: {  // required
          spanId: string;  // required
          traceId: string;  // required
        }[];
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Remove Annotation Queue Items

Removes the referenced spans from the annotation queue.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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 ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
        "span_ids": List[str],  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
      removeAnnotationQueueItemsRequest: {  // required
        spanIds: string[];  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

### 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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "annotation_queue_id": str,  # required
        "item_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      annotationQueueId: string;  // required
      itemId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.