Skip to main content
All requests require an API key in the X-API-Key header. See API Reference for authentication details.

List Devices

Discover the device and OS permutations that can be requested for cloud runs.
GET /api/v1/devices — Returns 200 OK
Optional query parameters are platform (android or ios) and physical (true or false). Each model appears once with its supported os_versions.
Example response (abbreviated):
Choose a model and one of its os_versions. For iOS simulators, fast_os_versions identifies choices with an optimized startup path. Every returned combination is supported.

Run Flows

Trigger flow execution. Returns a batch_id to poll via Run Status and a batch_url to view or share the entire batch in the dashboard.
POST /api/v1/flows/run — Returns 200 OK

Request Body

string
App bundle identifier (mobile). Required for mobile runs. If no app has this bundle ID and platform yet, the request returns 404 with the response header X-Autosana-Error: build_not_found.
string
ios or android. Required with bundle_id.
string
Web app identifier. Required for web runs. For mobile runs, optionally pass it with bundle_id and platform to pick the app that was uploaded with that app_id; omit it to run the app identified by bundle ID alone. Passing your bundle ID as app_id is the same as leaving it out.
string
Optional. Pin the run to a specific build (UUID) instead of the app’s active build — useful for testing a particular CI/CD build. The build must belong to the resolved app, otherwise the request returns 404. To find the build for a commit, see List App Builds.A build uploaded from a branch other than your default branch may run your code-managed flows as they are at its commit. See Branch builds run at their commit.
string
Optional. Run your code-managed flows as they are on a branch or at a commit, instead of as they are on your default branch. Pass a branch name or a full 40-character commit SHA, together with repo_full_name, and select with flow_ids, suite_ids, labels, folder_ids, or folder_paths. Flows and suites stored in that repo use their files at that commit. Flows and suites created in the dashboard run as saved.Without app_build_id, the build comes from the ref: the build uploaded for that commit, or for a branch, its newest build. If no build matches, the request returns 404; the app’s active build is never used. That 404 carries the response header X-Autosana-Error: build_not_found. To wait while another CI job uploads the build, retry on that header with a time limit; the GitHub Action waits 10 minutes. If the header never clears, check bundle_id, platform, and app_id for typos. Autosana reads the ref from GitHub, so the repo must be connected through the Autosana GitHub App.resolve_suite_context, suite_overrides, and parallelize_flows work the same with ref, except with folder_paths (see below). For a flow stored in the repo, suite_overrides must name a suite stored in the same repo that contains the flow at that commit; otherwise the request returns 400.
string
Repository in owner/repo format, exactly as connected to Autosana. Required with ref. Returns 404 if the repo isn’t connected to your organization.
string[]
Suite UUIDs to run. At least one of suite_ids, flow_ids, labels, folder_ids, or, with ref, folder_paths is required.
boolean
Optional suite execution override. Explicit true or false takes precedence over each suite’s saved Run flows in parallel setting. Omit it or send null to use the saved suite setting.
string[]
Flow UUIDs to run. At least one of suite_ids, flow_ids, labels, folder_ids, or, with ref, folder_paths is required.When provided, suite auth instructions and suite-scoped variables are resolved automatically unless resolve_suite_context is set to false. See Suite context for individual flows below.
string[]
Label names to run (e.g. ["smoke", "checkout"]). Runs the union of the suites and flows carrying any of these labels; a flow already covered by a matched suite runs once. Returns 400 if nothing matches. See Run by Label.
string[]
Folder UUIDs to run. Copy one from the folder’s ⋯ menu on the Flows page (Copy folder ID), or list them with the MCP folders_list tool.Runs every suite and flow beneath each folder, at any depth. Each suite runs in full, including flows it holds that are filed in other folders. A flow that belongs to a suite runs only as part of that suite, so the folder skips it when the suite is elsewhere. The folder also skips a flow that flow_ids lists, so that flow runs once. Every other flow runs on its own, without a suite’s auth instructions or suite-scoped variables.The response and Run Status include name: the folder’s name, or for several folders the first three names followed by “and N more”.
  • With ref, a folder from that repo runs as it is at the ref, the same as folder_paths below. A folder from a different repo returns 400.
  • With a branch build’s app_build_id, a folder from that repo can run as it is at the build’s commit. See Branch builds run at their commit.
  • A broken file beneath the folder at that commit: 400 naming the file.
  • Unknown folder: 404 with Folder not found: <ids>.
  • Nothing to run in the folders and nothing else selected: 404. When every flow there belongs to a suite outside those folders, the message says so.
  • 503 with Running folders is not available yet. Try again in a few minutes. while Autosana finishes an update. Retry later.
string[]
Folders to run by path below .autosana/, for example Auth/Onboarding. Requires ref and repo_full_name. Can’t be combined with all, flow_ids, suite_ids, labels, folder_ids, suite_overrides, or resolve_suite_context.Runs every suite and flow beneath each folder as they are at the ref, the same way folder_ids does. Flows and suites created in the dashboard and filed in the folder also run, as saved. Use it for a folder that exists only on a branch.
  • Unknown path: 404 with folder '<path>' does not exist at the ref.
  • Invalid path: 400 with folder path '<path>' is not valid. Use a path below .autosana/, for example Auth/Onboarding.
  • A broken file beneath the folder: 400 naming the file.
  • A suite beneath the folder that wouldn’t run all of its tests: 400 with suite '<key>' would not run all of its tests: <reason>.
  • Nothing to run in the folders and nothing else selected: 404 with No active suites or flows are in the selected folder(s).
  • Every flow in the folders belongs to a suite outside them, and nothing else is selected: 404 with Each flow in the selected folder(s) belongs to a suite outside those folders. Run that suite instead.
boolean
default:"true"
When running individual flows via flow_ids, whether to look up the flow’s suite and run auth instructions first. Defaults to true. Set to false to run the flow without suite auth or suite-scoped variables — useful for unauthenticated smoke tests or flows that handle login themselves.
object
Optional. When a flow belongs to multiple suites, pass a JSON object mapping each ambiguous flow_id to the suite_id whose auth instructions and variables should be used, e.g. {"<flow_id>": "<suite_id>"}. Ignored when resolve_suite_context is false.
string | object
Key-value variables to attach to the build being run (the pinned app_build_id if provided, otherwise the active build) and inject into flow instructions via ${env:KEY}. Accepts a string ("KEY1=VALUE1,KEY2=VALUE2") or a JSON object ({"KEY1": "VALUE1"}). See Build Variables.
string
For web apps: which browser to run the flow in. One of:
  • chrome — real Google Chrome (default). Includes proprietary codecs (H.264, AAC) and Widevine DRM. Use this unless you have a specific reason to pick another browser.
  • chromium — open-source Chromium. No proprietary codecs, no DRM, deterministic and vendor-neutral.
  • firefox — Mozilla Firefox stable.
  • edge — Microsoft Edge stable.
Aliases accepted: Chrome / Google Chrome → chrome; msedge / Microsoft Edge → edge. Ignored for mobile runs.
string
Optional. Two-letter ISO country code, such as MX. The run’s browser or device traffic leaves from that country. Web runs and Android emulator runs only: not iOS, physical devices, or local devices. See Proxy location.
string
Optional. Language and region the app opens in, such as de-DE, or a bare language such as de. Works on every platform and device. See Language & region.
array
Optional for web apps. Override the app’s default Chrome extensions for this run. Each entry can be an extension app UUID or an object that pins an exact build:
Omit this field to inherit the web app’s attached defaults. Pass [] to run without extensions. When extensions load, web_browser defaults to chrome; chrome and chromium run as requested, edge runs in Chromium, and firefox is rejected with a 400 because Chrome extensions are not supported there.
object
Optional for mobile apps. Selects the execution target and, when specified, the exact supported device permutation. Fields are physical (defaults to false), model (for example, "Pixel 10 Pro"), and os_version (for example, "17"). Set model or os_version to "latest" to explicitly request rolling resolution for that field. This lets you pin one while keeping the other current. For a real device, match sets how strictly each pinned field must match when the device is busy: {"model": "exact"}, {"os_version": "exact"}, or both. Fields default to "similar", which allows the closest free device. Use List Devices to discover valid combinations. Omit it to use the recommended default. A request with no supported match fails fast with a clear error. For an iOS simulator, use physical: false with a listed iPhone or iPad model and iOS version. For a real iOS device, use physical: true and an .ipa build.
object[]
Use instead of device to choose each device of a two-device flow. Pass exactly two entries in Device 1, Device 2 order. A run can mix one-device and two-device flows: one-device flows use the first entry, and a two-device flow run with device (or with neither field) uses that selection for both devices. Both entries must select virtual devices (physical: false) or both must select real devices (physical: true). Model and OS can be exact, "latest", or omitted for rolling resolution. Each real-device entry also takes match (for example {"model": "exact"}). Both devices use the run’s app build and platform.
See Multi-Device Testing for a complete setup and execution guide.
For example, keep the model and OS current on every run:

Suite context for individual flows

When you trigger a single flow via flow_ids, Autosana resolves the suite it belongs to and runs that suite’s Auth Instructions first — the same behavior as running the flow manually from the dashboard.
If a flow belongs to multiple suites, the request returns 400 unless you pass suite_overrides mapping that flow to one of its suite UUIDs, e.g. {"660e8400-e29b-41d4-a716-446655440001": "550e8400-e29b-41d4-a716-446655440000"}.

Branch builds run at their commit

When you send a branch build’s app_build_id with flow_ids, suite_ids, labels, or folder_ids and no ref, Autosana can run your code-managed flows as they are at the build’s commit — as if you had passed that commit as ref. A pull request’s CI then tests the pull request’s flow changes against the pull request’s build. This applies to any branch other than your default branch, including long-lived ones like develop or release/*, not only pull request branches. The build you named still runs. This happens when all of these hold:
  • The build was uploaded with a full 40-character commit_sha, a branch_name, and a repo_full_name (see Confirm Upload).
  • That GitHub repo is connected to your organization through an active Autosana GitHub App installation, with code-managed flows turned on.
  • branch_name isn’t the repo’s default branch.
  • At least one selected flow, suite, or folder is stored in that repo, and none is stored in a different repo.
  • Unless resolve_suite_context is false: no selected flow from the repo belongs to a suite created in the dashboard, and each suite_overrides entry names a selected flow and, for a flow from the repo, a suite from the same repo.
Otherwise the run uses the flows from your default branch. This changes what existing CI jobs that send a branch build’s app_build_id run. To keep running your default branch’s flows, pass repo_full_name and set ref to your default branch. If GitHub doesn’t know the commit, or the repo is too large to read, the run uses the flows from your default branch. If GitHub is unavailable, the request fails with an error you can retry. If the build’s commit deletes, renames, or breaks the file of a flow or suite you selected, the request also fails; the error names the flow’s key or the file. When the run uses the build’s commit, every flow in it, including ones created in the dashboard, gets the repository context (.autosana/autosana.md) at that commit. The response includes inferred_ref:
A flow added in a pull request exists only on that branch until it merges. If every flow you select is like that and you select no suite, a request that doesn’t run at a commit returns 400 naming the flow and, when Autosana knows it, its pull request. Pass ref with the branch’s head commit to run it.

Example Request

Example: Run with Chrome extensions

All dependency apps and pinned builds must belong to the same organization as the primary web app. Duplicate app IDs are loaded once; conflicting build pins return 400.

Example Response

flow_run_count counts the flows that will run. snoozed_flow_count counts the snoozed flows the run skipped. A request that names exactly one flow in flow_ids or flow_keys, with no suite, label, or folder selector, runs it even when it is snoozed. A run with folder_ids or folder_paths also returns the run’s name, for example "name": "Checkout". Other runs leave name out here, and Run Status returns it as null, with one exception. A branch run from MCP that is attached to the branch’s open pull request also has a name in Run Status, for example "name": "suite 'Smoke' on feature/login".

Run Status

Poll execution status for a batch triggered by Run Flows.
GET /api/v1/runs/status — Returns 200 OK

Query Parameters

string
required
The batch_id from /api/v1/flows/run.

Example Request

Example Response

app.id is the app’s ID: the bundle ID for a mobile app, or its custom app_id when it was uploaded with one. app.bundle_id is always the bundle ID, so use it if you match on bundle ID. For a web app both hold the app ID. Each run group also includes:
  • status: common values include creating, pending, queued, running, reviewing, verifying, terminating, terminated, passed, failed, error, and skipped. Treat this list as non-exhaustive. Poll until a terminal status rather than switching on every value.
  • runs[].status: each run’s own status. It takes the same values, plus installing: the run’s device is ready and its app is installing. The run then becomes running when its test starts, or goes back to queued if the install stops first. The group’s own status stays queued or running meanwhile.
  • source: how it was triggered (ci, dashboard, schedule, or mcp)
  • actor: who triggered it, as { id, name, type }, where type is user, system, or api_key
  • dependency_app_build_ids: exact Chrome extension build UUIDs loaded for the group
  • snoozed_runs: snoozed flows the group skipped, each with status snoozed. They never appear in runs.
summary.snoozed_flows counts snoozed flows. No other count includes them. A group whose flows are all snoozed has status passed and an empty runs. Runs triggered with an API key (this endpoint, MCP, CI) are attributed to the key itself: type is api_key, id is the key’s ID, and name is the key’s name from your dashboard. source and actor may be null for older runs.

Get Run Results

Get full details of a run, including metadata, summary, the raw run recording URL, and all actions with screenshot URLs. Use the id from individual runs in the Run Status response.
GET /api/v1/runs/{run_id} — Returns 200 OK

Path Parameters

string
required
UUID of the run. Available in the runs[].id and snoozed_runs[].id fields from Run Status.
A run whose flow was snoozed and skipped has status snoozed. A run whose device is ready while its app installs has status installing.

Example Request

Example Response

Hook runs

object[]
Each setup, teardown and by-name (${hooks:Name}) hook the run executed, oldest first. Suite-level hooks aren’t included.
  • hook_type — setup, teardown, or action (called by name)
  • slug — the hook’s slug
  • name — the hook’s display name
  • status — running, passed, failed, or error (the hook couldn’t run, for example a configuration problem)
  • source — repo (a hook file at the run’s commit, or your working copy on --local or --cloud runs) or database (a hook stored in Autosana — added in the dashboard or synced from your default branch)
  • hook_id — the stored hook’s ID; null for a repo file
  • script_sha256 — SHA-256 of the hook body that ran; null for built-in hooks
  • frozen — true when the body was captured at run start. When false, script_sha256 hashes the hook’s current saved body, which may differ from what ran if the hook was edited since.
On older frozen runs, source, hook_id and script_sha256 may be null. They are also null, along with name, when two hooks of the same type in one run share a slug.

Artifact URLs

string[]
Exact Chrome extension build UUIDs loaded for this run.
object[]
Per-device metadata and artifact URLs for a two-device run, ordered by device_index. Each entry includes model and OS metadata and that device’s recording, performance, device-log, and network-log URLs. Single-device runs return an empty array and continue to use the top-level artifact fields below.
string | null
Public URL for the raw, unannotated MP4 recording of the run. null when the run did not produce a recording.
string | null
Time-series performance metrics (memory, CPU, web vitals) as JSON.
string | null
Device log (Android logcat / iOS syslog) or browser console log (web), as plain text or JSONL.
string | null
HTTP requests captured during the run, as JSONL — one entry per request with method, url, status, resource_type, duration_ms, response_size, etc. Failed requests (DNS, abort, CORS) appear with status: 0 and an error string.Produced for web and iOS runs (iOS from the cloud simulator; apps that pin their TLS certificate aren’t captured). null when no traffic was captured. See Network Traffic.
Any of these may be null if the artifact wasn’t produced for that run. performance_data_url, device_log_url and network_log_url, here and in devices, are signed links that expire after 24 hours. Fetch the run again for fresh ones. Actions from a two-device run include device_index (1 or 2).

Terminate Run

Terminate an in-progress flow group run. run_id may be a flow group run ID from Run Flows (flow_group_run_ids) or a flow run ID from Run Status / Get Run Results.
Passing a flow run ID terminates the entire parent group, including every sibling flow in that suite or batch, not just the one run.
POST /api/v1/runs/terminate returns 200 OK

Request Body

string
required
UUID of a flow group run or a flow run.
Pending runs are terminated immediately. Queued or running groups are marked terminating. Already-terminal runs return action: "none". Unknown or other-organization IDs return 404. To watch termination finish, reuse the batch_id from Run Flows and poll Run Status until that group’s status is terminal (terminated, skipped, passed, failed, or error). The terminate response does not include batch_id. You can also poll Get Run Results with the original flow run ID until that flow reaches any terminal status. Children that never started may be skipped rather than terminated.

Example Request

This example passes a flow run ID. The response echoes that ID in run_id and the resolved parent group in flow_group_run_id.

Example Response

string
The run_id you sent (flow group run or flow run).
string
The parent group that was actually terminated. Same as run_id when you passed a group ID.
string
Current group status after the request. Typically terminated or terminating. When action is none, this is the group’s existing terminal status (passed, failed, error, terminated, or skipped).
string
Human-readable outcome, for example "Marked for termination (worker will finalize)" or "Already in terminal state".
string
terminated (pending run stopped immediately), terminating (worker will finalize), or none (already terminal).

Polling

Poll /api/v1/runs/status every 10-15 seconds until is_complete is true.