Queues

Queues are ordered lists of prompts to be processed by a headless agent. Each queue item progresses through a pending → in_progress → succeeded | failed lifecycle. Use dequeue to claim the next pending item atomically; use markItem to record the outcome when done.

list

client.queues.list(params?: QueueListParams): Promise<Page<QueueSummary>>

Paginated list of queues owned by the authenticated user. Returns a navigable Page<T>.

Parameters

const page = await client.queues.list({ pageSize: 12 });

return {
  total: page.total,
  page: page.page,
  hasNext: page.hasNext,
  items: page.items.map((q) => ({
    id: q.id,
    name: q.name,
    pendingCount: q.pendingCount,
    totalCount: q.totalCount,
  })),
};

listAll

client.queues.listAll(params?: QueueListParams): AsyncIterable<QueueSummary>

Async iterator that walks every page automatically. Use for await; break stops further requests.

const names = [];
for await (const queue of client.queues.listAll()) {
  names.push(queue.name);
  if (names.length >= 20) break;
}
return names;

create

client.queues.create(input: QueueCreateInput): Promise<QueueCreateResponse>

Create a new queue. Returns the created queue's id, name, and description. Throws PromptyValidationError (400) if the name is blank or exceeds 80 characters, and 409 if a queue with that name already exists.

Input

const queue = await client.queues.create({
  name: "sdk-test-queue",
  description: "Created by the docs runner",
});

// Clean up immediately
const items = await client.queues.listItems(queue.id);
for (const item of items.items) {
  await client.queues.removeItem(queue.id, item.id);
}

return { id: queue.id, name: queue.name };

listItems

client.queues.listItems(queueId: string, params?: QueueItemListParams): Promise<Page<QueueItem>>

Paginated list of items in a queue. Optionally filter by status. Throws PromptyNotFoundError on 404.

Parameters

listAllItems

client.queues.listAllItems(queueId: string, params?: QueueItemListParams): AsyncIterable<QueueItem>

Async iterator over all items in a queue, walking pages automatically.

addItem

client.queues.addItem(queueId: string, promptId: string): Promise<QueueItem>

Add a prompt to the queue. The item starts with status "pending". The prompt must be accessible to the authenticated user. Throws PromptyNotFoundError on 404.

dequeue

client.queues.dequeue(queueId: string): Promise<DequeuedItem | null>

Claim the next pending item from the queue, atomically marking it "in_progress". Returns the item with its compiledPrompt included, or null if no pending items remain. Throws PromptyNotFoundError on 404.

Important: once claimed, call markItem to record the outcome. Items left "in_progress" indefinitely will block the queue.

markItem

client.queues.markItem(queueId: string, itemId: string, input: MarkQueueItemInput): Promise<void>

Record the final outcome of a queue item. Status must be "succeeded" or "failed"; these are the only terminal states. An optional notes field (max 2000 chars) captures processing details.

Input

removeItem

client.queues.removeItem(queueId: string, itemId: string): Promise<void>

Permanently remove an item from the queue. The item is deleted regardless of its current status.

Type reference

type QueueItemStatus = "pending" | "in_progress" | "succeeded" | "failed";
type TerminalQueueItemStatus = "succeeded" | "failed";

interface QueueSummary {
  id: string;
  name: string;
  description: string;
  pendingCount: number;
  inProgressCount: number;
  succeededCount: number;
  failedCount: number;
  totalCount: number;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

interface QueueItem {
  id: string;
  queueId: string;
  promptId: string;
  status: QueueItemStatus;
  notes: string;
  promptTitle: string;
  currentVersion: number;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
}

interface DequeuedItem extends QueueItem {
  compiledPrompt: string;
}

interface QueueCreateInput {
  name: string;
  description?: string;
}

interface QueueCreateResponse {
  id: string;
  name: string;
  description: string;
}

interface MarkQueueItemInput {
  status: TerminalQueueItemStatus;
  notes?: string;
}

interface QueueListParams {
  page?: number;
  pageSize?: number; // 1–100, default 12
  search?: string;
  signal?: AbortSignal;
}

interface QueueItemListParams {
  page?: number;
  pageSize?: number; // 1–100, default 20
  status?: QueueItemStatus;
  signal?: AbortSignal;
}