Documentation

Everything you need to submit tasks, stream results, and build reliable AI agent workflows.

Installation

Install the SDK for your language.

TypeScript / Node.js

npm install @queueai/sdk

Python

pip install queueai

Authentication

Pass your API key when constructing the client. Get yours from the dashboard.

# .env
QUEUEAI_API_KEY=qai_live_...

Never commit API keys. Use environment variables or a secrets manager.

Quickstart

Submit a task, stream events as they happen, and get a final result.

TypeScript

import { QueueAI } from "@queueai/sdk"

const queue = new QueueAI({ apiKey: process.env.QUEUEAI_API_KEY })

const task = await queue.submit({
  name: "deep-research",
  input: { question: "What changed in AI dev tooling in 2026?" },
  model: {
    primary: "anthropic/claude-opus-4-8",
    fallback: "anthropic/claude-sonnet-4-6",
  },
  budget: { maxCostUsd: 1.50 },
  retries: 3,
})

for await (const event of task.stream()) {
  console.log(`[${event.step}] ${event.status} — ${event.tokens} tokens`)
}

const result = await task.wait()
console.log("Done:", result.output)
console.log(`Cost: $${result.totalCostUsd.toFixed(4)}`)

Python

from queueai import QueueAI

queue = QueueAI(api_key=os.environ["QUEUEAI_API_KEY"])

task = queue.submit(
    name="deep-research",
    input={"question": "What changed in AI dev tooling in 2026?"},
    model={
        "primary": "anthropic/claude-opus-4-8",
        "fallback": "anthropic/claude-sonnet-4-6",
    },
    budget={"max_cost_usd": 1.50},
    retries=3,
)

for event in task.stream():
    print(f"[{event.step}] {event.status} — {event.tokens} tokens")

result = task.wait()
print("Done:", result.output)

Task schema

All fields accepted by queue.submit().

namerequired

Identifier for the task type. Used in dashboards and logs.

string
inputrequired

Arbitrary JSON passed to the task executor.

object
model.primaryrequired

Primary model in provider/model format, e.g. anthropic/claude-opus-4-8.

string
model.fallback

Fallback model(s) used when primary is unavailable or over budget.

string | string[]
budget.maxCostUsd

Hard USD ceiling. Task halts gracefully when exceeded.

number
budget.maxTokens

Hard token ceiling across all steps.

number
retries

Max retry attempts per step on transient failure. Default: 0.

number
checkpoints

Named human-in-the-loop gates. Execution pauses at each until approved.

string[]
timeout

Task-level timeout in milliseconds.

number
metadata

Arbitrary key/value pairs attached to the task record.

object

Streaming events

task.stream() yields TaskEvent objects as the task executes.

id

Unique event ID.

string
step

Human-readable step name, e.g. planning, worker-2, synthesis.

string
status

Current status of this step.

running | retrying | waiting | done | error
message

Optional status message.

string?
tokens

Tokens consumed so far in this step.

number?
costUsd

Running cost in USD for this step.

number?
timestamp

Unix timestamp in milliseconds.

number
data

Optional step output data.

unknown?

Orchestration patterns

QueueAI is built around a small set of composable orchestration patterns. Understanding them helps you build tasks that are reliable, cost-efficient, and easy to debug.

Browse the pattern library →