---
title: "Start an autopilot run"
method: POST
path: "/autopilot/runs"
tags: ["Autopilot"]
---

# Start an autopilot run

`POST /autopilot/runs`

## Request

- Base URL: `https://api.emailchaser.com/r`
- URL: `https://api.emailchaser.com/r/autopilot/runs`
- Auth: HTTP bearer

Creates an autopilot run for the given website. The run works autonomously up to the approval gate: it builds the customer profile, drafts the sequence and checks, without spending credits, that prospects match the profile. Nothing is spent, bought or sent before a human approves the run: no credits are reserved and no prospect is revealed until then, and approving is what reveals the first batch of prospects. When budgetUsd is given the sized budget plan is returned and snapshotted on the run, and targetProspects defaults to the plan's monthly prospect capacity. The plan's domain and mailbox counts are a ceiling, not a quote: one infrastructure order buys at most 10 domains, can place fewer mailboxes than the plan, and buys nothing when the workspace already has a connected sending account. Its dollar figures are an estimate, and an order is charged at the prices in force when it is placed. replyMode controls how inbound replies are handled (off, draft, approve, auto; default draft); auto sends AI reply drafts for interested replies without review. Available on every plan, and requires an active subscription. A workspace may have only one run awaiting approval at a time, and a limited number of starts per day.

## Request body

- ModelsStartAutopilotRunRequest
  - `budgetUsd` number: BudgetUsd, when given, sizes a budget plan that is snapshotted on the run. The plan's domain and mailbox counts are a ceiling for what the run buys after approval (one order holds at most 10 domains and can place fewer mailboxes), and its dollar figures are an estimate.
  - `chosenDomain` string: ChosenDomain is the .com domain to buy for a starter-kit run. Checked with the registrar before the run is created.
  - `mailboxUsernames` string[]: MailboxUsernames are the one to three mailbox local parts to create on that domain. The mailboxes are created under the workspace owner's real name.
  - `maxMailboxes` integer: MaxMailboxes caps the budget plan's infrastructure. 0 means no cap.
  - `replyMode` string: ReplyMode is how inbound replies are handled: off, draft (default), approve, or auto. Auto sends AI reply drafts for interested replies without review - opt in deliberately.
  - `scaleRun` boolean: ScaleRun marks this run as a scale step for a workspace that already sends. Without it the run buys nothing when a mailbox is already connected, which is right for a first run and wrong for a second one. The run's infrastructure is sized as an ADDITION to the current fleet: with BudgetUsd by the same planner GET /autopilot/scale-plan uses for CUSTOM, without it by the DOUBLE preset. Ignored with StarterKit. The run still parks at the approval gate.
  - `starterKit` boolean: StarterKit buys the launch starter kit instead of sizing from a budget: one .com domain, up to three mailboxes and the first 50 prospects, at the intro prices when the workspace is still eligible for them. ChosenDomain and MailboxUsernames are required with it, BudgetUsd and TargetProspects are ignored, and the resulting run can only be APPROVED in the Emailchaser app - this API refuses to approve one.
  - `targetProspects` integer: TargetProspects is how many prospects the run reveals per sourcing batch: the first batch once the run is approved, then each top-up. No prospect is revealed and no credit is spent before approval. When omitted and a budget is given, it is derived from the budget plan; when 0 or omitted without a budget, the runner default batch applies.
  - `website` string, required: Website is the company website the run is seeded from.

## Response `201`

The created run, with the plan when a budget was given

- ModelsAutopilotRunResult
  - `plan` ModelsAutopilotPlanResponse
    - `credits` integer
    - `creditsUsd` number
    - `domains` integer
    - `expectedMeetingsPerMonth` number: ExpectedMeetingsPerMonth is a planning ESTIMATE on pessimistic funnel assumptions, not a promise.
    - `feasible` boolean: Feasible reports whether the budget covers a usable setup at all.
    - `firstMonthUsd` number: FirstMonthUsd includes the one-off setup on top of the recurring cost.
    - `mailboxes` integer
    - `mailboxesMonthlyUsd` number
    - `monthlySends` integer
    - `notes` string[]: Notes explains anything worth surfacing to a human.
    - `prospectsPerMonth` integer
    - `recurringUsd` number: RecurringUsd is the steady-state monthly cost.
    - `setupUsd` number: SetupUsd is the one-off cost in the first month (mailbox setup fees and annual domain registrations).
  - `run` ModelsAutopilotRunResponse
    - `approvedAt` string: ApprovedAt is when a human approved the run (RFC3339), or null.
    - `approvedByUserId` integer: ApprovedByUserID is who approved the run, or null.
    - `audit` ModelsAutopilotAuditEvent[]
      - `actor` string
      - `at` string
      - `message` string
      - `stage` string
    - `autoOptimizeVariants` boolean
    - `autoTopupProspects` boolean
    - `campaignId` integer
    - `chosenDomain` string: ChosenDomain and MailboxUsernames are the customer's own choices on a starter-kit run, empty on every other run.
    - `createdAt` string
    - `icpId` integer
    - `id` integer
    - `killSwitch` boolean: KillSwitch reports whether the run has been permanently halted.
    - `lastAdvancedAt` string: LastAdvancedAt is when the run last made progress (RFC3339), or null.
    - `lastError` string
    - `mailboxUsernames` string[]
    - `prospectSearchId` integer
    - `prospectShortfall` integer: ProspectShortfall is how many prospects short of its target a starter-kit run finished sourcing. Zero on a run that reached it.
    - `replyMode` string
    - `scaleRun` boolean: ScaleRun reports whether this run buys infrastructure on top of a workspace that already sends.
    - `starterKit` boolean: StarterKit reports whether this run buys the fixed launch starter kit. A starter-kit run cannot be approved over this API: POST /autopilot/runs/{id}/approve answers 409 and the customer approves it in the Emailchaser app.
    - `status` string: Status is one of: pending, building_icp, writing_sequence, sourcing_prospects, awaiting_approval, provisioning_infrastructure, running, paused, completed, failed. A run is at sourcing_prospects twice: before approval it checks for free that prospects match, after approval (approvedAt set) it reveals the first batch, which spends credits.
    - `targetProspectCount` integer
    - `website` string

## Other responses

- `400`: Invalid request body
- `401`: Unauthorized - invalid or missing API key
- `402`: The workspace does not hold enough prospect credits for the first batch the run reveals once approved: the run's prospect target, capped at what a single increment can reserve, priced at credits.ActionProspectReveal credits per prospect. A pre-flight check only; starting reserves nothing (code insufficient_credits, with have/need counts)
- `403`: Autopilot requires an active subscription
- `429`: A run is already awaiting approval, or too many runs have been started today
- `500`: Failed to start the autopilot run
- `503`: The registrar could not be reached to check the chosen starter-kit domain; retry

---

[API](https://skmtc.dev/emailchaser/apis/emailchaser-api.md) · [All operations](https://skmtc.dev/emailchaser/apis/emailchaser-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emailchaser/apis/emailchaser-api/revisions/8b114990abb7?raw)