Tasks

Start a task

Start a task from a prompt. Returns at once: store task_id, then stream or poll. Pass task_id to send the prompt to an existing task (202 while it queues).

post/task

Request

Base URL
https://api.autumn.ai
URL
https://api.autumn.ai/task
Auth
- API key in header X-API-Key
- or HTTP bearer

Request body

waitboolean

Accepted for compatibility; starting a task always returns immediately.

task_idstring nullable

Continue this task instead of creating one.

namestring nullable

Display name. Derived from the prompt when omitted. Applies only when the task is created; ignored on an existing task_id.

clarifyboolean

Allow one blocking planning question before work starts. Default false: plan and execute without asking.

input_filesstring[] nullable

Task-local filenames returned by POST /validate-upload.

outputobject nullable

The output artifact to collect: id, kind, path, name; for research also schema, schema_order, target_count. Applies only when the task is created; ignored on an existing task_id.

input_schemaobject nullable

Column types of input_rows. Applies only when the task is created; ignored on an existing task_id.

input_rowsobject[] nullable

Rows to enrich, one object per row. Applies only when the task is created; ignored on an existing task_id.

rulesobject nullable

Each value is a rule in plain language; the key names it. Applies only when the task is created; ignored on an existing task_id.

countinteger nullable

Target row count. Applies only when the task is created; ignored on an existing task_id.

target_countinteger nullable

Alternative to count. Applies only when the task is created; ignored on an existing task_id.

versionstring nullable

Model tier. ranger (default): most capable. scout: faster. wren: cheapest, admin plans only. Fixed for the life of the task. Admin-plan keys may also pin a build with ranger@v-<sha12>, a variant name, or a version id.

source_dataobject nullable

Caller metadata stored on the task and returned with it.

promptstring nullable

Natural-language task for Autumn. One of prompt or message is required.

messagestring nullable

Alias of prompt.

Example request

{
  "prompt": "Find 10 Series A AI security companies and return name, website, funding stage, and source URLs."
}

Response

Task accepted. Store task_id.

task_idstring required

namestring nullable

statusstring nullable

Legacy; use state and done. plan (idle, or finished), execute (working), accepted (queued), deleted.

phase'plan' | 'execute' nullable

Legacy; use state and done.

activitystring nullable

Legacy; use state and done. idle, queued, planning, executing or thinking. queued is waiting for a free slot and starts on its own. Finished is idle.

output_countinteger nullable

credits_usedinteger nullable

created_atstring nullable

updated_atstring nullable

poll_after_sinteger nullable

Seconds to wait before polling status again.

status_urlstring nullable

task_urlstring nullable

API resource URL, relative to the API server. Open the chat in the browser at https://platform.autumn.ai/?task={task_id}.

output_urlstring nullable

stream_urlstring nullable

statestring nullable

A2A lifecycle state: submitted, working, input-required, completed, canceled or failed.

doneboolean nullable

True for input-required, completed, canceled and failed.

stagestring nullable

Current stage while the task is active.

messagestring nullable

Latest public-facing task message.

answerstring nullable

Full saved assistant answer for a completed chat task without output rows.

progressobject nullable

Rows saved and optional target count.

elapsed_sinteger nullable

Elapsed seconds in the current or most recent run.

queue_positioninteger nullable

Place in line for a queued task, or null when not queued.

queued_countinteger

Pending queued follow-ups.

outcomestring nullable

Normalized completed outcome.

errorobject nullable

Public failure code and recovery guidance.

nextobject nullable

Suggested next action and API call.

versionstring nullable

Changes when public task status changes.

app_urlstring nullable

Open the task in the Autumn app.

Example response

{
  "task_id": "8fab6f34",
  "name": "Series A AI security companies",
  "status": "execute",
  "phase": "execute",
  "activity": "executing",
  "output_count": 10,
  "poll_after_s": 5,
  "status_url": "/task/8fab6f34/state",
  "task_url": "/task/8fab6f34",
  "output_url": "/task/8fab6f34/output",
  "stream_url": "/task/8fab6f34/stream",
  "queue": {
    "position": 3,
    "eta_s": 240
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.