Quickstart

Pick the way in that matches where you’re working:

You’re using	Do this
Your own code	Create an API key in Settings → Developer, then follow the steps below.
ChatGPT, Claude.ai or another MCP client	Add `https://api.autumn.ai/mcp` as a custom connector and sign in. See Hosted MCP.
A coding agent with a shell (Claude Code, Codex, Cursor)	Paste the prompt from Connect your agent. It signs you in without copying a key.

One POST starts a cloud agent that does the research. You keep the task_id, wait while it works, then read finished rows. One host, and every route is in the spec:

Base URL:  https://api.autumn.ai
OpenAPI:   https://api.autumn.ai/openapi.json
Auth:      X-API-Key: YOUR_AUTUMN_API_KEY

1. Get an API key

Create an API key in Settings → Developer at platform.autumn.ai, then put it in your environment:

export AUTUMN_API_KEY=your_key

Every request sends it as X-API-Key (or Authorization: Bearer).

2. Start a task

TASK_ID=$(curl -sS -X POST "https://api.autumn.ai/task" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "List the top 20 posts on Hacker News today with their points",
    "clarify": false
  }' | sed -n 's/.*"task_id": *"\([^"]*\)".*/\1/p')
echo "Started $TASK_ID"

import os, requests

AUTUMN = "https://api.autumn.ai"
HEADERS = {"X-API-Key": os.environ["AUTUMN_API_KEY"]}

task = requests.post(
    f"{AUTUMN}/task",
    headers=HEADERS,
    json={"prompt": "List the top 20 posts on Hacker News today with their points",
          "clarify": False},
).json()

task_id = task["task_id"]

const AUTUMN = "https://api.autumn.ai";
const HEADERS = {
  "X-API-Key": process.env.AUTUMN_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(`${AUTUMN}/task`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    prompt: "List the top 20 posts on Hacker News today with their points",
    clarify: false,
  }),
});
const { task_id } = await res.json();

The response is your handle on the task:

{
  "task_id": "8fab6f34",
  "state": "working",
  "done": false,
  "status": "execute",
  "phase": "execute",
  "activity": "executing",
  "stream_url": "/task/8fab6f34/stream",
  "output_url": "/task/8fab6f34/output"
}

Store task_id. It stays valid after the run finishes.

3. Wait for a status change

import time

def get_status(task_id):
    while True:
        r = requests.get(
            f"{AUTUMN}/task/{task_id}",
            headers=HEADERS,
            params=dict(wait=50),
        )
        if r.status_code in (429, 503):
            time.sleep(float(r.headers.get("Retry-After", 5)))
            continue
        if not 200 <= r.status_code < 300:
            raise RuntimeError(r.json().get("message") or r.text)
        return r.json()

task = get_status(task_id)
while not task["done"]:
    task = get_status(task_id)

if task["state"] == "input-required":
    print(task["message"])
elif task["state"] in {"failed", "canceled"}:
    error = task.get("error") or {}
    raise RuntimeError(
        error.get("message") or error.get("code") or task.get("message") or task["state"]
    )

async function getStatus(taskId) {
  while (true) {
    const r = await fetch(`${AUTUMN}/task/${taskId}?wait=50`, { headers: HEADERS });
    if (r.status === 429 || r.status === 503) {
      const seconds = Number(r.headers.get("Retry-After") || 5);
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
      continue;
    }
    const body = await r.json();
    if (!r.ok) throw new Error(body.message || "Status request failed");
    return body;
  }
}

let task = await getStatus(task_id);
while (!task.done) {
  task = await getStatus(task_id);
}

if (task.state === "input-required") {
  console.log(task.message);
} else if (task.state === "failed" || task.state === "canceled") {
  const error = task.error || {};
  throw new Error(error.message || error.code || task.message || task.state);
}

headers=$(mktemp)
trap 'rm -f "$headers"' EXIT
while :; do
  response=$(curl -sS -D "$headers" -w '\n%{http_code}' \
    "https://api.autumn.ai/task/$TASK_ID/state?wait=50" \
    -H "X-API-Key: $AUTUMN_API_KEY")
  status=${response##*$'\n'}
  task=${response%$'\n'*}
  if [ "$status" = 429 ] || [ "$status" = 503 ]; then
    retry_after=$(awk 'tolower($1) == "retry-after:" { gsub("\r", "", $2); delay=$2 } END { print delay }' "$headers")
    sleep "${retry_after:-5}"
    continue
  fi
  if [ "$status" -lt 200 ] || [ "$status" -ge 300 ]; then
    printf 'Status request failed (HTTP %s): %s\n' "$status" "$task" >&2
    exit 1
  fi
  printf '%s\n' "$task" | grep -q '"done": *true' && break
done

state=$(printf '%s\n' "$task" | grep -o '"state": *"[^"]*"' | head -n 1 | cut -d'"' -f4)
case $state in
  completed)
    curl -sS "https://api.autumn.ai/task/$TASK_ID/output?format=csv" \
      -H "X-API-Key: $AUTUMN_API_KEY" -o rows.csv
    ;;
  input-required)
    printf '%s\n' "$task" | grep -o -E '"message": *"([^"\\]|\\.)*"' | head -n 1 | sed -E 's/^"message": *"//; s/"$//; s/\\"/"/g; s/\\\\/\\/g'
    ;;
  failed|canceled)
    printf 'Task %s: %s\n' "$state" "$task" >&2
    exit 1
    ;;
  *)
    printf 'Task %s: %s\n' "$state" "$task" >&2
    exit 1
    ;;
esac

wait=50 waits up to 50 seconds for a status change. Repeat the request until done is true; input-required is done for the current turn and its question is in message. See Task lifecycle for the state table. Prefer status events over polling? See Live messages.

4. Read the rows

curl -sS "https://api.autumn.ai/task/$TASK_ID/output?limit=100" \
  -H "X-API-Key: $AUTUMN_API_KEY"

rows = requests.get(
    f"{AUTUMN}/task/{task_id}/output",
    headers=HEADERS,
    params={"limit": 100},
).json()["rows"]

for row in rows:
    print({k: v["value"] for k, v in row.items() if isinstance(v, dict) and "value" in v})

const { rows } = await fetch(
  `${AUTUMN}/task/${task_id}/output?limit=100`,
  { headers: HEADERS },
).then((r) => r.json());

Each field arrives as a cell, {"value": ..., "source_id": ...}, so every value carries the source behind it. Flatten to plain values when you just want the data, and keep the cells when you need provenance. For CSV, request GET /task/{task_id}/output?format=csv&limit=100; the response contains the current page and sends X-Next-Cursor when more rows remain. See Outputs.

5. Continue instead of restarting

The task_id is durable. To refine or extend results, send the same task new instructions rather than starting over:

curl -sS -X POST "https://api.autumn.ai/task/$TASK_ID/continue" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Add the submitting user for every row, and find 10 more"}'

If the task is running, the continue is queued and the response is 202 with state: "submitted" and queue_position.

What a task can do

Data extraction: scrape sites and collect structured rows with sources
Enrichment: fill in people, companies, jobs, contacts, filings
Multi-step research: search across many sources, compare, and summarize
List building: find N entities that match criteria, with per-row evidence
Continuation: refine, expand, or fix a previous task without starting over

Structured output

Declare the exact columns you want back.

Live messages

Stream events as the agent works.

Follow-up tasks

Continue the same task with new instructions.

Task API

Every route, field, and response shape.

Get started

Core concepts

Guides

Best practices

Use with agents

1. Get an API key

2. Start a task

3. Wait for a status change

4. Read the rows

5. Continue instead of restarting

What a task can do

Next

Structured output

Live messages

Follow-up tasks

Task API

​1. Get an API key

​2. Start a task

​3. Wait for a status change

​4. Read the rows

​5. Continue instead of restarting

​What a task can do

​Next

Structured output

Live messages

Follow-up tasks

Task API

1. Get an API key

2. Start a task

3. Wait for a status change

4. Read the rows

5. Continue instead of restarting

What a task can do

Next