API reference — Coasty Computer Use API

Building with an AI assistant?Generate a ready-made prompt tailored to Cursor, Claude Code, ChatGPT, or any LLM.PRIMARY AUTOMATION · START HEREtask runsone goal, driven to doneworkflowsmany tasks, one programmachinesmanaged Linux or Windowsuse finer control when neededPRIMITIVES · YOU OWN EXECUTIONpredictstateless stepsessionsstateful loopgroundfind coordinatesparsecode to actionsStart with task runs, workflows, and machines. Drop to prediction primitives only when your application needs to own the control loop.Start with a task run: give Coasty a goal and a machine, then let the agent drive to completion. Use workflows when an automation needs many tasks, branches, loops, approvals, or shared outputs. Machines provide the managed computer those tasks operate.The prediction endpoints are lower-level primitives for teams that need to own the control loop themselves. Use sessions for a stateful screenshot loop, predict for a stateless step, grounding for coordinates, and parse for structured actions. Everything is normal HTTPS to https://coasty.ai/v1, so you can choose the highest-level surface that fits the job and drop down only when you need finer control.Start withUse it whenTask runsOne goal should be driven autonomously from start to verified completion.WorkflowsMany tasks need sequencing, branching, loops, budgets, or human approval.MachinesThe agent needs a managed Linux or Windows computer with browser, terminal, and files.PrimitivesYour application needs direct control over every screenshot, prediction, and action.API keyscope ✓reserve $run model200 + usageX-Credits-*failsrefund + 5xxX-Credits-Refunded401 / 403 / 402 short-circuit before any chargeEvery billed call is charged before the model runs and automatically refunded if it fails — the X-Credits-Refunded header confirms the refund.Every API-key-authenticated request must include your secret key. The four health probes are public, and webhook ingress uses its documented Coasty-Signature HMAC credential instead. For API-key operations, the canonical form is the X-API-Key header, but Authorization: Bearer <key> works too: a blank X-API-Key falls through to the Bearer header. Pick one form and send the raw key.

Do not paste the literal text Bearer inside X-API-Key; that is the single most common first-day mistake and it returns 401 INVALID_API_KEY. Keys are created and revoked from the API keys page. Treat a key like a password: keep it server-side, store it in an environment variable, and never commit it or ship it in client-side code.PrefixKindBehavioursk-coasty-live-LiveRuns the real model and draws down your USD wallet balance.sk-coasty-test-TestReturns mock responses and never bills. Ideal for local dev and CI.Prefer test keys while you wire up your integration. An sk-coasty-test-key never bills and runs against mock VMs, yet exercises the exact same request and response shapes (its X-Credits-Charged and usage.cost_centsare always 0), so you can build and run CI confidently before flipping to a live key.Your first autonomous task needs an API key and a machine. Grab a test key from the API keys page (it never bills), then use an existing machine or provision one. Set the key in your shell:Start the task with POST /v1/runs. Replace the example machine_id, describe the outcome in task, and send an Idempotency-Key so a retried create cannot start a duplicate run. The complete example starts the run and follows it to a terminal state:The create response begins at queued. Coasty then drives the machine, records each step, and finishes as succeeded, failed, cancelled, or timed_out. Your application can poll, subscribe to the event stream, or receive signed webhooks; it does not need to execute each prediction itself.NextGo toUnderstand task fields, lifecycle, and resultsTask runsFollow progress without pollingStreaming eventsTurn the task into repeatable multi-step automationWorkflowsOwn every screenshot and action yourselfPrediction primitivesTask runs are the default starting point for autonomous work. Workflows build on them, machines host them, and prediction primitives remain available when your application needs direct control over the loop.

POST /v1/runstask + machineagent loopseescreenshotthinkpredictactapplyverifydonepass / failSSE eventslive stream, resumablewebhookHMAC-signed callbackshuman takeoverpause → resumePOST a task + machine and Coasty runs the whole loop for you — streaming events over SSE, calling your webhook on lifecycle changes, and pausing for a human when asked.A run hands the agent a task and a machine, then drives it to completion on our side. The agent loops autonomously, verifies its own work (pass or fail), can pause for a human when it hits a wall, bills $0.05 per completed step from your dollar API wallet ($0.08/step on the legacy v1 engine), and streams every event live. You start one call and watch, instead of running the predict loop yourself.Create a run with POST /v1/runs. The two required fields are machine_id and task. The response is an agent.run object with status of queued, plus a one-time webhook_secret you store to verify webhooks. Send an Idempotency-Key header to make a retried create safe.FieldRequiredDescriptionmachine_idYesThe machine the agent will drive.taskYesThe natural-language goal to accomplish.cua_versionNoModel family. v5 by default; v1 / v3 / v4 / v5 on all tiers.instructionsNoExtra guidance appended to the base prompt.system_promptNoA preamble placed ahead of the base prompt.max_stepsNoHard cap on agent steps (default 50).deadline_secondsNoWall-clock budget; the run becomes timed_out if breached.on_awaiting_humanNoWhat to do when a human is needed: pause (default), fail, or cancel.awaiting_human_timeout_secondsNoHow long to wait for a human before timing out.webhook_urlNoHTTPS endpoint for lifecycle callbacks (https only).metadataNoArbitrary JSON echoed back on the run object.EndpointPurposePOST /v1/runsStart a run. Returns the run plus a one-time webhook_secret.GET /v1/runsList runs. Filter with ?status= and ?limit=.GET /v1/runs/{id}Fetch a single run and its current status.

GET /v1/runs/{id}/eventsServer-Sent Events stream of the run (see Streaming events).POST /v1/runs/{id}/cancelCancel a run that has not reached a terminal state.POST /v1/runs/{id}/resumeHand control back after a human takeover.FieldTypeDescriptionidstringUnique run id, prefixed run_.objectstringAlways "agent.run".statusstringqueued, running, awaiting_human, succeeded, failed, cancelled, or timed_out.machine_idstringThe machine the agent is driving.taskstringThe natural-language goal you submitted.cua_versionstringModel family: "v5" (default). Any of "v1" / "v3" / "v4" / "v5", available on all tiers.instructionsstringExtra guidance appended to the base prompt (nullable).max_stepsintHard cap on agent steps (default 50).on_awaiting_humanstringWhat to do when a human is needed: pause, fail, or cancel.steps_completedintHow many agent steps have run so far.credits_chargedintInternal cost units billed (1 unit = $0.01). See cost_cents for the dollar amount.cost_centsintDollar cost so far, in cents (USD).resultobject{ passed, status, summary, verdict? } once the run finishes.errorobject{ code, message } when the run failed (nullable).awaiting_human_reasonstringWhy the run paused for a human (nullable).metadataobjectThe metadata you attached at create time.llmobject|nullNon-secret BYOK echo when the run opted into your own key: { provider, model, key_fingerprint, key_source, key_scrubbed }. Never contains the key itself. See Bring your own model.webhook_urlstringWhere lifecycle events are POSTed (nullable).created_atstringISO-8601 creation timestamp.started_atstringWhen the run left the queue (nullable).awaiting_human_sincestringWhen the run last paused for a human (nullable).finished_atstringWhen the run reached a terminal state (nullable).request_idstringId of the create request, for support and tracing.A run moves through queued to running, can bounce between running and awaiting_human, and ends in one of succeeded, failed, cancelled, or timed_out.

Terminal states are immutable, so it is always safe to stop polling once you reach one. Runs need the runs:read and runs:write scopes, granted to new keys by default.GET /v1/runs/{id}/events returns a Server-Sent Events stream so you can follow a run as it happens, instead of polling. Each event has a type and a numeric id (the sequence number). If your connection drops, reconnect and replay everything you missed by sending the last sequence you saw as a Last-Event-ID header, or as the ?after= query parameter. The stream closes after the done event.EventMeaningstatusThe run moved to a new status (running, awaiting_human, succeeded, etc.).textA chunk of the agent's natural-language narration.reasoningA chunk of the model's private reasoning, if exposed.tool_callThe agent invoked a tool (a click, a keypress, a navigation).tool_resultThe result of the most recent tool call.awaiting_humanThe run paused and is waiting for a human to take over.resumedControl was handed back after a human takeover.stepA full agent step completed; carries steps_completed.billingIncremental billing update (credits_charged, cost_cents).errorA non-fatal or fatal error occurred during the run.doneTerminal event. The stream closes after this is sent.Some steps need a person: a captcha, a one-time code, a judgment call. When the agent reaches one and on_awaiting_human is pause, the run moves to awaiting_human and emits an awaiting_human event with a reason. A human completes the blocking step (in the same machine session), then you hand control back with POST /v1/runs/{id}/resume and an optional note. Resume is only valid while the status is awaiting_human.Detect the pause from either the run object (status == awaiting_humanwith awaiting_human_reason set), the SSE awaiting_human event, or the run.awaiting_humanwebhook. After resume, the run returns to running and emits a resumed event. Set on_awaiting_human to fail or cancel at create time if you would rather the run stop than wait for a human.Pass a webhook_url (https only) when you create a run and we POST a signed callback at each lifecycle transition.