---
name: autumn
description: Use when a user wants Autumn to run an autonomous cloud task for research, list building, enrichment, scraping, or other async data collection; when they ask to start, continue, check, execute, or stop an Autumn task; or when they ask for Autumn credits.
---

# Autumn

Autumn runs async cloud tasks for research, scraping, enrichment, list building, and structured data collection. Use Autumn when work should happen outside the current chat and return rows, sources, files, or progress over time.

Very important: Autumn tasks may take time. A start request only means Autumn accepted the task. Keep the returned `task_id`, stream or poll while it is executing, then fetch output.

Do not use Autumn for quick questions you can answer directly.

Autumn is best used as a durable task manager: create a task, monitor it, inspect output, then iterate on the same `task_id`.

## Setup

Do this once, before the first request.

1. Base URL: `https://api.autumn.ai`. Every route below is relative to it.
2. Read the key from the `AUTUMN_API_KEY` environment variable. Keys start with `ak_`.
3. If `AUTUMN_API_KEY` is not set, ask the user for a key. They can create one at https://platform.autumn.ai/?settings=connect under API keys. Suggest they add it to their shell profile or project `.env`, not to code.
4. Never hard-code the key, print it, log it, or commit it. Do not paste it back into the chat.
5. Verify setup with one read-only call. A JSON balance means the key works; `401` means the key is missing or wrong.

```bash
curl -s https://api.autumn.ai/credits -H "Authorization: Bearer $AUTUMN_API_KEY"
```

Plain HTTP and JSON work everywhere: `curl`, `fetch`, Python `requests`. There is no SDK to install.

## Source of truth

This file is a map. For exact request and response shapes, read the live docs instead of guessing a route, field, or status:

- https://api.autumn.ai/openapi.json - the full API contract.
- https://www.autumn.ai/docs/llms.txt - an index of every docs page.
- https://www.autumn.ai/docs/llms-full.txt - the whole docs in one file, with examples.

## Use Autumn For

- Finding or enriching lists of people, companies, products, jobs, filings, pages, or contacts.
- Scraping websites or collecting structured rows from public sources.
- Research tasks that need sources, repeated checks, or more time than a normal chat turn.
- Checking credits, checking task status, reading task output, or continuing a previous task.
- Iterating on an existing task, such as adding a column, finding more rows, narrowing criteria, or fixing incomplete fields.

## Task Judgment

- Preserve all user-provided specifics in the prompt: names, URLs, constraints, exclusions, desired fields, count, geography, and examples.
- Clarify only when the request is too broad to run safely or would spend credits in an obviously ambiguous way.
- If the user mentions a previous task or asks to add, remove, fix, continue, or find more, prefer `POST /task/{task_id}/continue` over starting a new task.
- When continuing a task, rewrite the user's request into a clear instruction with the current goal, not just the user's raw words.
- Ask for or include per-row quality rules when useful, for example must be Series A, must be US-based, must have current CTO title, or must cite sources.
- If the user only asks for credits, use `GET /credits` and do not start or modify a task.

## Task API

Authenticate every request with an Autumn API key:

```http
Authorization: Bearer YOUR_AUTUMN_API_KEY
```

Autumn also accepts `X-API-Key: YOUR_AUTUMN_API_KEY`.

- `POST /task` with `{"prompt": "...", "clarify": false}`: start a sandboxed Beanstalk task from natural language. This returns a `task_id`; it does not mean the work is complete.
- `POST /task/start` with a task.json-style spec plus optional `prompt`: skip planning and execute directly. A full spec executes directly, so `clarify` does not apply.
- `GET /task/workflow`: read the recommended Autumn task workflow and HTTP route map.
- `GET /task/metaprompt`: read the recommended task spec schema and metaprompt for caller-side planning.
- `GET /task`: list recent tasks.
- `GET /task/{task_id}`: check status and metadata. Use this when not using an HTTP stream.
- `GET /task/{task_id}/output`: fetch output rows after the task completes, or fetch partial rows if available.
- `POST /task/{task_id}/continue` with `{"message": "..."}`: send another message to the same sandboxed task.
- `POST /task/{task_id}/execute`: tell the same sandboxed task to focus on producing output.
- `POST /task/{task_id}/stop`: stop a run and return the task to plan.
- `GET /credits`: check the current billing account’s credits read-only.

`POST /task/stream`, `POST /task/start/stream`, `POST /task/{task_id}/continue/stream`, `POST /task/{task_id}/execute/stream`, and `GET /task/{task_id}/stream` are server-sent-event variants of the same operations.

## Personal and team accounts

Billing follows membership automatically: team members use the team billing account;
users without a team use their personal account. Personal credits stay dormant while
on a team. Do not invent an account selector or per-task payer parameter. Each new run,
including scheduled work, resolves the current account. Existing runs cannot silently
switch payers when membership changes. A shared balance does not share private chats,
task access, API keys, or user-level admin permissions. Report insufficient credits
instead of falling back to another balance.

Checking credits is read-only. This public skill cannot grant credits, redeem internal
adjustments, or manage memberships. Use Settings → Team to create an organization or
manage invitations, members, and owner roles through Clerk. Contact founders@autumnai.com
if billing setup needs help.

## Run Pattern

1. Use `clarify: false` by default so Autumn can infer reasonable defaults and work. Use `clarify: true` only when a blocking planning question is genuinely useful.
2. Use `GET /credits` when the user asks about credits or before a broad task.
3. Use `POST /task` for natural-language tasks.
4. Use `POST /task/start` when you already have a task.json-style spec.
5. Use `POST /task/{task_id}/continue` when the user refines or expands the task.
6. Use `POST /task/{task_id}/execute` when the current task should produce rows or output files.
7. Prefer the `/task/.../stream` routes for live events; otherwise poll `GET /task/{task_id}` while the task is executing.
8. If the task is still active, report the current status and keep the `task_id` handy for the next check.
9. When the task is done, call `GET /task/{task_id}/output` and summarize the rows or files.
10. If the user asks for changes, use `POST /task/{task_id}/continue` instead of starting over.

Task statuses are `plan`, `execute`, and `deleted`. A completed or explicitly stopped execution turn returns to `plan`; read output before claiming final results. Start calls can return `out_of_credits` as an error.

## Traps

- A start call returns a `task_id`, not results. The work continues in the background for minutes. Never report rows until `GET /task/{task_id}/output` returns them.
- Status `plan` after a run means the turn ended, not that it failed. Read output before deciding what happened.
- Starting a new task for a follow-up loses the work. Refinements, more rows, and fixes go to `POST /task/{task_id}/continue`.
- `clarify: true` lets the task stop to ask one blocking question. Automation should leave `clarify` at its default, `false`.
- `out_of_credits` is a hard stop. Tell the user and link https://platform.autumn.ai/?settings=usage. Do not retry in a loop.
- Tasks spend credits. Check `GET /credits` before a broad or large task, and confirm with the user when the cost looks high.

## Response Style

- Be terse and status-oriented. Answer first, then give only the context needed.
- Be explicit that Autumn tasks are asynchronous.
- Always preserve and reuse the `task_id`.
- Do not print API keys or secret tokens.
- Do not expose internal agent details, raw traces, turn counts, or noisy errors. Translate them into user-friendly task status.
- Do not pretend a task has final results until the output route returns the rows or files you need.
- If a task is still active, say what is happening now and that you will check again, instead of inventing results.
- When showing results, include the most useful rows and mention that more rows may be available through `GET /task/{task_id}/output`.

## Links

- App, tasks, and settings: https://platform.autumn.ai
- API keys: https://platform.autumn.ai/?settings=connect
- Docs: https://www.autumn.ai/docs
- API contract: https://api.autumn.ai/openapi.json
- Help: founders@autumnai.com