Maestro API Overview

Q: How do I upload my app and Maestro flows via the API?

POST your binary to the /maestro/app endpoint and your flow ZIP to /maestro/:id/tests with HTTP basic auth (API key and secret). The response returns IDs you use when starting the run. See the Upload App and Upload Maestro Flows sections.

Q: How do I find a run by its build name?

GET /maestro/runs/:build_name to resolve a build name straight to its project ID and run ID(s) in one request, instead of listing projects and scanning each one. A build can map to multiple runs (one per device), so the response is always an array. See the Find Run by Build Name section .

TestingBot provides a REST API to upload apps, run Maestro flows, and retrieve information about your Maestro projects and runs.

In the documentation below, a Maestro project using a :project_id consists of a mobile application that was uploaded together with a zipped set of Maestro flow files.

A Maestro project can have multiple test runs, depending on how many device configurations (capabilities) you specified when you started the tests.

All API endpoints require authentication using your TestingBot API key and secret, which you can obtain from the Member area.

Base URL	Authentication
`https://api.testingbot.com/v1/app-automate/maestro`	HTTP Basic Auth (API key:secret)

CLI Alternative

For most use cases, we recommend using the TestingBot CLI instead of the REST API directly. The CLI handles uploading your app, flows and running tests in a single command:

# Install the CLI
npm install -g @testingbot/cli

# Authenticate
testingbot login

# Run Maestro tests (handles upload + run automatically)
testingbot maestro app.apk ./flows --device "Pixel 8" --deviceVersion "14"

The CLI provides:

Automatic app and flow uploads
Real-time progress and streaming output
Automatic report downloads
Simpler authentication

Use the REST API directly when you need programmatic access or custom integration workflows.

Upload App

Upload your Android (.apk/.aab) or iOS (.ipa/.app) application to TestingBot. This creates a new Maestro project and returns a project ID.

Method	Endpoint
`POST`	`/app-automate/maestro/app`

Parameters

Name	Type	Required	Description
`file`	file	Yes	The app file to upload (.apk, .aab, .ipa, .app or .zip)

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/app" \
-F "file=@/path/to/your/app.apk"

Response

{
  "id": 17876,
  "app": {
    "app_url": "https://...",
    "icon_url": "https://...",
    "app_version": "1.0.0",
    "bundle_id": "com.example.app"
  }
}

Save the returned id - you'll need it for uploading flows and running tests.

Upload Maestro Flows

Upload your Maestro flow files (as a .zip archive) to an existing project. This replaces any previously uploaded flows.

Method	Endpoint
`POST`	`/app-automate/maestro/:id/tests`

Parameters

Name	Type	Required	Description
`id`	integer	Yes	The project ID returned from the app upload
`file`	file	Yes	A .zip file containing your Maestro flow YAML files

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/tests" \
-F "file=@/path/to/flows.zip"

Response

{
  "id": 17876,
  "flows": [
    {
      "id": 123,
      "name": "login_flow"
    }
  ]
}

Run Maestro Tests

Start running your Maestro flows on one or more devices. You can specify multiple device configurations to run tests in parallel.

Method	Endpoint
`POST`	`/app-automate/maestro/:id/run`

Parameters

Name	Type	Required	Description
`id`	integer	Yes	The project ID
`capabilities`	array	Yes	Array of device configurations to run tests on
`maestroOptions`	object	No	Additional Maestro options (version, env, flows, tags). See Test Options.
`shardSplit`	integer	No	Group flows into N chunks, each chunk running on a separate device. When omitted, each flow runs in its own session on the same device.
`metadata`	object	No	CI/CD metadata stored with the run (e.g. `commitSha`, `pullRequestId`, `repoOwner`, `repoName`, `branch`). Displayed in the TestingBot dashboard.

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{"capabilities":[{"platformName":"Android","version":"14","deviceName":"Pixel 8"}]}' \
-H "Content-Type: application/json"

Response

{
  "success": true,
  "id": 17876,
  "runs": [
    {
      "id": 18809,
      "capabilities": {
        "platformName": "Android",
        "version": "14",
        "deviceName": "Pixel 8"
      },
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
          "report": "<xml>...</xml>",
          "requested_at": "2025-11-28T09:15:00.000Z",
          "completed_at": "2025-11-28T09:16:00.000Z",
          "status": "DONE",
          "test_case_id": 456
        }
      ]
    }
  ]
}

Error Responses

Status Code	Description
`402`	Insufficient credits to run this test. Please upgrade your account to continue running Maestro tests.

List Maestro Projects

Retrieve a paginated list of all your Maestro projects.

Method	Endpoint
`GET`	`/app-automate/maestro`

Query Parameters

Name	Type	Default	Description
`offset`	integer	0	Number of records to paginate
`count`	integer	10	Number of records to return

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro"

Response

{
  "data": [
    {
      "id": 17876,
      "name": "Maestro Project 17876",
      "created_at": "2025-11-28T08:12:31.000Z",
      "updated_at": "2025-11-28T08:12:31.000Z",
      "completed": false,
      "app": {
        "app_url": "https://...",
        "icon_url": "https://...",
        "app_version": "2.7.50420",
        "bundle_id": "org.wikipedia"
      },
      "flows_url": "https://...",
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
        }
      ],
      "runs": [18809, 18854, 18863, 18866]
    }
  ],
  "meta": {
    "offset": 0,
    "count": 10,
    "total": 25
  }
}

List Maestro Runs

Retrieve a paginated list of all your Maestro runs across every project, newest first. This is a lightweight endpoint: it returns run metadata only and does not inflate the (potentially large) flow reports, so it is well suited to dashboards and CI lookups. For a single run's full results and reports, use Get Run Info.

Method	Endpoint
`GET`	`/app-automate/maestro/runs`

Query Parameters

Name	Type	Default	Description
`offset`	integer	0	Number of records to paginate
`count`	integer	10	Number of records to return

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/runs?count=10&offset=0"

Response

{
  "data": [
    {
      "id": 18809,
      "project_id": 17876,
      "name": "maestro-android-PR12730-26648200708",
      "status": "DONE",
      "success": 1,
      "capabilities": {
        "platformName": "Android",
        "version": "14",
        "deviceName": "Pixel 8"
      },
      "created_at": "2025-11-28T09:15:00.000Z",
      "completed_at": "2025-11-28T09:16:00.000Z"
    }
  ],
  "meta": {
    "offset": 0,
    "count": 10,
    "total": 25
  }
}

The status and success fields reflect the run's last-known state. A run is finished once status is DONE or FAILED.

Find Run by Build Name

Look up runs by their build name (the name capability you set when starting the tests). This lets you resolve a build name straight to its project_id and run_id in a single request, instead of listing projects and scanning each one.

A single build can fan out to multiple runs (for example one run per device configuration), so this endpoint always returns an array of every matching run.

Method	Endpoint
`GET`	`/app-automate/maestro/runs/:build_name`

Parameters

Name	Type	Required	Description
`build_name`	string	Yes	The build name to look up, matched against the run's `name`. Remember to URL-encode names that contain spaces or special characters.

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/runs/maestro-android-PR12730-26648200708"

Response

{
  "data": [
    {
      "id": 18809,
      "project_id": 17876,
      "name": "maestro-android-PR12730-26648200708",
      "status": "DONE",
      "success": 1,
      "capabilities": {
        "platformName": "Android",
        "version": "14",
        "deviceName": "Pixel 8"
      },
      "created_at": "2025-11-28T09:15:00.000Z",
      "completed_at": "2025-11-28T09:16:00.000Z"
    }
  ]
}

Error Responses

Status Code	Description
`404`	No run matches the supplied build name on your account.

Use the returned project_id and id (run ID) to fetch full results from Get Run Info or download the JUnit Report.

Get Maestro Project Info

Retrieve details about a specific Maestro project, including all its runs.

Method	Endpoint
`GET`	`/app-automate/maestro/:id`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:id"

Response

{
  "runs": [
    {
      "id": 18809,
      "status": "DONE",
      "capabilities": {
        "version": "16",
        "deviceName": "Pixel 9",
        "platformName": "Android"
      },
      "success": 1,
      "report": "",
      "options": {},
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
          "report": "<xml>...</xml>",
          "requested_at": "2025-11-28T09:15:00.000Z",
          "completed_at": "2025-11-28T09:16:00.000Z",
          "status": "DONE",
          "test_case_id": 456
        }
      ]
    }
  ],
  "success": true,
  "completed": true
}

Run Status Values

Status	Description
`WAITING`	Run is queued and waiting for a device
`READY`	The test is running on the device
`DONE`	Run has completed
`FAILED`	Run failed to complete
`CANCELLED`	Run was cancelled before it finished, either through the API or from the dashboard

Get Run Info

Retrieve detailed information about a specific Maestro run. Use this to poll for completion status.

Method	Endpoint
`GET`	`/app-automate/maestro/:project_id/:run_id`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id"

Replace :project_id with your project ID and :run_id with the run ID.

Response

{
  "id": 18809,
  "status": "DONE",
  "capabilities": {
    "version": "16",
    "deviceName": "Pixel 9",
    "platformName": "Android"
  },
  "flows": [
    {
      "id": 123,
      "name": "login_flow",
      "report": "<xml>...</xml>",
      "requested_at": "2025-11-28T09:15:00.000Z",
      "completed_at": "2025-11-28T09:16:00.000Z",
      "status": "DONE",
      "test_case_id": 456
    }
  ],
  "success": 1,
  "report": "",
  "options": {},
  "completed": true
}

Poll this endpoint to check if the test has finished. The completed field will be true when the run has completed.

JUnit Report

Retrieve the JUnit XML report for a completed Maestro run. This is useful for CI/CD integration.

Method	Endpoint
`GET`	`/app-automate/maestro/:project_id/:run_id/junit_report`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/junit_report"

Response

{
  "junit_report": "<?xml version=\"1.0\"?><testsuites>...</testsuites>"
}

The junit_report field contains the XML-formatted JUnit report generated by Maestro.

Cancel Maestro Run

Immediately cancel a queued or running Maestro run. Cancelling stops the run from requesting any more devices, closes out every flow that has not finished yet, releases the device session the run is currently holding, and drops any request the run still has queued on the device grid, so you stop being billed for it right away. Flows that already completed keep their results and reports.

Method	Endpoint
`POST`	`/app-automate/maestro/:project_id/:run_id/cancel`

Parameters

Name	Type	Required	Description
`project_id`	integer	Yes	The project ID
`run_id`	integer	Yes	The ID of the run to cancel

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/cancel"

Response

{
  "success": true,
  "run": {
    "id": 18809,
    "project_id": 4211,
    "name": "nightly-regression",
    "status": "CANCELLED",
    "success": 0,
    "capabilities": {
      "platformName": "Android",
      "version": "16",
      "deviceName": "Pixel 9"
    },
    "created_at": "2025-11-28T09:15:00.000Z",
    "completed_at": "2025-11-28T09:15:42.000Z"
  },
  "cancelled_flow_count": 3
}

cancelled_flow_count is how many flows were still queued or running when the cancel landed. A 0 means the run held no unfinished flows; its device session, if it had one, is still released.

Error Responses

Status Code	Description
`403`	Your account is read-only and cannot start or stop tests.
`404`	No project or run with those IDs exists on your account.
`409`	The run had already reached a terminal state (`DONE`, `FAILED` or `CANCELLED`), so there was nothing to cancel.

A cancelled run cannot be resumed, and its individual flows cannot be retried with Retry Maestro Flow. Use Retry Maestro Run to start the whole run again on the same capabilities.

Stop Maestro Run

Alias of Cancel Maestro Run, kept for existing integrations. It does exactly the same thing, with one difference: it always answers 200, so stopping a run that has already finished is a no-op rather than a 409. It returns only a success flag, not the run. New integrations should use the cancel endpoint.

Method	Endpoint
`POST`	`/app-automate/maestro/:project_id/:run_id/stop`

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/stop"

Response

{
  "success": true
}

Retry Maestro Flow

Re-run a single flow from a Maestro run. This creates a new flow attempt inside the same run and schedules it on the same device configuration, which is useful for retrying a flaky or failed flow without starting a whole new run.

Method	Endpoint
`POST`	`/app-automate/maestro/:project_id/:run_id/:flow_id/retry`

Parameters

Name	Type	Required	Description
`project_id`	integer	Yes	The project ID
`run_id`	integer	Yes	The run ID
`flow_id`	integer	Yes	The ID of the flow (from the run's `flows` array) to retry

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/:flow_id/retry"

Response

{
  "success": true,
  "flow": {
    "id": 124,
    "name": "login_flow",
    "status": "WAITING",
    "requested_at": "2025-11-28T09:20:00.000Z"
  }
}

The retry runs as a new flow attempt inside the same run. Poll the Get Run Info endpoint to track the new flow's status via its returned id.

Retry Maestro Run

Re-run an entire Maestro run. This creates a brand new run on the same device configuration (capabilities) and options as the original, re-scheduling every flow. Use this when you want to repeat a full run rather than a single flow.

Method	Endpoint
`POST`	`/app-automate/maestro/:project_id/:run_id/retry`

Parameters

Name	Type	Required	Description
`project_id`	integer	Yes	The project ID
`run_id`	integer	Yes	The ID of the run to retry

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/retry"

Response

{
  "success": true,
  "run": {
    "id": 18920,
    "capabilities": {
      "platformName": "Android",
      "version": "14",
      "deviceName": "Pixel 8"
    },
    "flows": [
      {
        "id": 125,
        "name": "login_flow",
        "status": "WAITING",
        "requested_at": "2025-11-28T09:25:00.000Z"
      }
    ]
  }
}

A new run is created with its own id. Poll the Get Run Info endpoint with that ID to track its status.

Frequently asked questions

Do I have to use the REST API or can I just use the TestingBot CLI?

For most workflows the TestingBot CLI is simpler since it handles upload, run and result polling in one command. The REST API is the right choice when you want fine-grained control, are integrating from a non-Node environment, or need to fetch artifacts asynchronously.

How do I upload my app and Maestro flows via the API?

POST your binary to the /maestro/app endpoint and your flow ZIP to /maestro/:id/tests with HTTP basic auth (API key and secret). The response returns IDs you use when starting the run. See the Upload App and Upload Maestro Flows sections.

How do I start a Maestro test run via the API?

POST to the run endpoint with the app and flow IDs from the upload step, plus your device target and any options. See the Run Maestro Tests section for the request body and response shape.

How do I fetch JUnit-style reports for CI?

GET the run's JUnit endpoint to receive a JUnit XML file with per-flow pass and fail results. Most CI runners can consume this format directly. See the JUnit Report section.

How do I find a run by its build name?

GET /maestro/runs/:build_name to resolve a build name straight to its project ID and run ID(s) in one request, instead of listing projects and scanning each one. A build can map to multiple runs (one per device), so the response is always an array. See the Find Run by Build Name section.

How do I cancel a running Maestro test?

POST to the cancel endpoint with the project ID and run ID. The run stops requesting devices, its unfinished flows are closed out, and the device session it holds is released, so billing stops right away. Flows that already finished keep their results. See the Cancel Maestro Run section for details.

Can I retry a single flow from a cancelled run?

No. A cancelled run cannot be reopened, so flow-level retry returns a 409 for it. Use Retry Maestro Run to run the whole thing again on the same capabilities.

How do I retry a single failed flow?

POST to the retry endpoint with the project ID, run ID and flow ID. This re-runs just that flow inside the same run instead of starting a whole new run. See the Retry Maestro Flow section.

How do I retry an entire run?

POST to the run-level retry endpoint with the project ID and run ID. This creates a new run on the same capabilities and options, re-scheduling every flow. See the Retry Maestro Run section.