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 OKplatform (android or ios) and physical
(true or false). Each model appears once with its supported os_versions.
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 abatch_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 OKRequest Body
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.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.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.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.Repository in
owner/repo format, exactly as connected to Autosana. Required with ref. Returns 404 if the repo isn’t connected to your organization.Suite UUIDs to run. At least one of
suite_ids, flow_ids, labels, folder_ids, or, with ref, folder_paths is required.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.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.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.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 asfolder_pathsbelow. A folder from a different repo returns400. - 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:
400naming the file. - Unknown folder:
404withFolder 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. 503withRunning folders is not available yet. Try again in a few minutes.while Autosana finishes an update. Retry later.
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:
404withfolder '<path>' does not exist at the ref. - Invalid path:
400withfolder path '<path>' is not valid. Use a path below .autosana/, for example Auth/Onboarding. - A broken file beneath the folder:
400naming the file. - A suite beneath the folder that wouldn’t run all of its tests:
400withsuite '<key>' would not run all of its tests: <reason>. - Nothing to run in the folders and nothing else selected:
404withNo 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:
404withEach flow in the selected folder(s) belongs to a suite outside those folders. Run that suite instead.
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.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.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.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.
Chrome / Google Chrome → chrome; msedge / Microsoft Edge → edge. Ignored for mobile runs.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.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.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.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.Use instead of See Multi-Device Testing for a complete setup and
execution guide.
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.Suite context for individual flows
When you trigger a single flow viaflow_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.
Branch builds run at their commit
When you send a branch build’sapp_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, abranch_name, and arepo_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_nameisn’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_contextisfalse: no selected flow from the repo belongs to a suite created in the dashboard, and eachsuite_overridesentry names a selected flow and, for a flow from the repo, a suite from the same repo.
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
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 OKQuery Parameters
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 includecreating,pending,queued,running,reviewing,verifying,terminating,terminated,passed,failed,error, andskipped. 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, plusinstalling: the run’s device is ready and its app is installing. The run then becomesrunningwhen its test starts, or goes back toqueuedif the install stops first. The group’s ownstatusstaysqueuedorrunningmeanwhile.source: how it was triggered (ci,dashboard,schedule, ormcp)actor: who triggered it, as{ id, name, type }, wheretypeisuser,system, orapi_keydependency_app_build_ids: exact Chrome extension build UUIDs loaded for the groupsnoozed_runs: snoozed flows the group skipped, each withstatussnoozed. They never appear inruns.
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 theid from individual runs in the Run Status response.
GET
/api/v1/runs/{run_id} — Returns 200 OKPath Parameters
UUID of the run. Available in the
runs[].id and snoozed_runs[].id fields from Run Status.status snoozed. A run whose device is ready while its app installs has status installing.
Example Request
Example Response
Hook runs
Each setup, teardown and by-name (
${hooks:Name}) hook the run executed, oldest first. Suite-level hooks aren’t included.hook_type—setup,teardown, oraction(called by name)slug— the hook’s slugname— the hook’s display namestatus—running,passed,failed, orerror(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--localor--cloudruns) ordatabase(a hook stored in Autosana — added in the dashboard or synced from your default branch)hook_id— the stored hook’s ID;nullfor a repo filescript_sha256— SHA-256 of the hook body that ran;nullfor built-in hooksfrozen—truewhen the body was captured at run start. Whenfalse,script_sha256hashes the hook’s current saved body, which may differ from what ran if the hook was edited since.
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
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.Public URL for the raw, unannotated MP4 recording of the run.
null when the run did not produce a recording.Device log (Android
logcat / iOS syslog) or browser console log (web), as plain text or JSONL.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.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.
POST
/api/v1/runs/terminate returns 200 OKRequest Body
Pending runs are terminated immediately. Queued or running groups are markedterminating. 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
run_id and the resolved parent group in flow_group_run_id.
Example Response
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).Human-readable outcome, for example
"Marked for termination (worker will finalize)" or "Already in terminal state".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.