--- title: "Run test" method: POST path: "/api/apps/{app_id}/testing-agent/executions" --- # Run test `POST /api/apps/{app_id}/testing-agent/executions` This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production. Starts a run of a test. The testing agent opens `url` in a cloud browser, signs in as a temporary test user, and works toward the test's goal. A report follows once the browser session ends. Leave `url` out and the run starts on the app's current preview, the same one [Get preview URL](/api-reference/get-preview-url) returns. If the preview isn't running, this call starts it first, so it can take noticeably longer. The run works against the app's test data, not its live data. To start on a different page, send `url` yourself. It must be on `base44.app` or `base44.com`, and a preview page also needs a fresh `_preview_token` from Get preview URL in its query, because each token works once and expires after 5 minutes. The call returns once the run is queued. A run that repeats an earlier one can come back already finished. Otherwise poll [Get test run](/api-reference/get-test-run) until `status` is no longer `pending`, `running` or `analyzing`. Then read the verdict with [Get test run report](/api-reference/get-test-run-report). A run costs credits, and `credits_charged` on the finished run shows how many. The call is refused when the workspace is out of credits. A run that runs out of credits partway through stops with `status` set to `paused` and `failure_reason` set to `out_of_credits`. A test runs one at a time. Starting it again while a run is still going returns a `409`. This is limited to 300 requests every 600 seconds per caller for each app. Some workspaces have a different limit. This endpoint accepts a personal API key belonging to a user with editor access to the app. Read-only keys and workspace API keys are refused. The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. ## Path parameters - `app_id` string, required — ID of the app. ## Request body - object - `flow_id` string, required — ID of the test to run. - `url` string — Page the run starts on. Leave it out to start on the app's current preview. ## Response `200` The queued run. - TestRun — One run of a test. - `id` string, required — ID of the run. - `app_id` string, required — ID of the app. - `flow_id` string, required — ID of the test this run belongs to. - `flow_goal` string, required — The test's goal when the run started. - `flow_role` string, nullable, required — Role the run signs in as, including one Base44 picked from the test's name or goal. Set once the run starts. `null` when the run uses no role. - `site_url` string, required — URL the run opened. - `status` 'pending' | 'running' | 'analyzing' | 'success' | 'failed' | 'timeout' | 'cancelled' | 'paused', required — Where the run is. `pending`, `running` and `analyzing` mean it's still going. `success` means the browser session finished, and `failed` means it didn't. `timeout`, `cancelled` and `paused` mean the run stopped early. The test passed when `goal_accomplished` is `true` and `failure_reason` isn't `platform` or `internal`. - `actions` TestRunStep[], required — Steps the agent took. Empty until the run finishes. - `step_title` string, required — Short description of the step. - `step_summary` string, required — What the agent did in this step and why. - `result_message` string, nullable, required — The agent's account of how the run went, or `null` before the run finishes. - `goal_accomplished` boolean, nullable, required — Whether the agent accomplished the goal, or `null` before the run finishes. Can be `true` on a run whose `failure_reason` is `platform` or `internal`, which counts as a technical failure. - `live_status` string, nullable, required — Short progress message for display, or `null` before the run starts. - `analysis_status` 'pending' | 'completed' | 'failed', nullable, required — Progress of the run's report. `completed` means [Get test run report](/api-reference/get-test-run-report) has it. `null` before the run reaches analysis. - `failure_reason` 'app' | 'platform' | 'internal' | 'out_of_credits', nullable, required — Why the run didn't pass, or `null` when no reason was recorded. `app` is a problem in your app. `platform` and `internal` are problems on Base44's side, so rerun the test. `out_of_credits` comes with status `paused`. - `credits_charged` number, nullable, required — Credits the run cost, or `null` before it's charged. - `started_at` string, nullable, required — When the browser session started, as an ISO 8601 UTC timestamp, or `null` while pending. - `completed_at` string, nullable, required — When the run ended, as an ISO 8601 UTC timestamp, or `null` while it's still going. - `created_date` string, required — When the run was requested, as an ISO 8601 UTC timestamp. - `updated_date` string, required — When the run last changed, as an ISO 8601 UTC timestamp. ## Other responses - `400` — `url`, or the app's preview when you leave `url` out, isn't on a Base44 host, or the workspace is out of credits. - `401` — Missing or invalid credentials. - `403` — You don't have editor access to this app, the app is blocked, or your API key is read-only or a workspace API key. - `404` — App or test not found. - `409` — The test already has a run going, the app's preview couldn't start because its code doesn't build, or your workspace requires an unlocked SSO session. - `422` — Validation Error - `429` — Rate limit exceeded. ## Changes - **2026-09-30** `63675fa5257c` — 1 info - endpoint added [Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/testing-agent/executions/post.md) --- [API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/e58d4ff7b1f8?raw)