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

## 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 `task_continue(task_id, message)` 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 `credits_balance()` and do not start or modify a task.

## Tools

- `task_start(prompt, clarify=false)`: start a Daytona-sandboxed Beanstalk task from natural language. This returns a `task_id`; it does not mean the work is complete.
- `task_start_direct(task, prompt="", clarify=false)`: start from a task.json-style spec plus optional prompt.
- `task_workflow()`: read the recommended Autumn task workflow and HTTP route map.
- `task_list()`: list recent tasks.
- `task_status(task_id)`: check status and metadata. Use this when not using an HTTP stream.
- `task_output(task_id, limit?)`: fetch output rows after the task completes, or fetch partial rows if available.
- `task_continue(task_id, message)`: send another message to the same sandboxed task.
- `task_execute(task_id)`: tell the same sandboxed task to focus on producing output.
- `task_stop(task_id)`: stop a run and return the task to plan.
- `credits_balance()`: check credits read-only.

## 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 `credits_balance` when the user asks about credits or before a broad task.
3. Use `task_start(prompt, clarify=false)` for natural-language tasks.
4. Use `task_start_direct(task, prompt="", clarify=false)` when you already have a task.json-style spec.
5. Use `task_continue` when the user refines or expands the task.
6. Use `task_execute` when the current task should produce rows or output files.
7. If using HTTP, prefer the `/task/.../stream` routes for live events. If using MCP tools, check `task_status(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 `task_output(task_id)` and summarize the rows or files.
10. If the user asks for changes, use `task_continue(task_id, message)` 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.

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

## HTTP Fallback

If MCP tools are unavailable, use the Task API with an Autumn API key:

```http
POST /task
POST /task/stream
POST /task/start
POST /task/start/stream
GET /task/workflow
GET /task
GET /task/{task_id}
GET /task/{task_id}/stream
GET /task/{task_id}/output
POST /task/{task_id}/continue
POST /task/{task_id}/continue/stream
POST /task/{task_id}/execute
POST /task/{task_id}/execute/stream
POST /task/{task_id}/stop
GET /credits
```

Authenticate with:

```http
Authorization: Bearer YOUR_AUTUMN_API_KEY
```

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

For MCP-compatible clients, configure the server URL `https://api.autumn.ai/mcp` with the `Authorization: Bearer YOUR_AUTUMN_API_KEY` header. If a client only supports named API-key headers, use `X-API-Key`.