Run test

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

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 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 until status is no longer pending, running or analyzing. Then read the verdict with 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.

<Note>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.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

{
  "flow_id": "68a1c2e4f0b3d9001a7e5c21",
  "url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"
}

{
  "id": "68a1c9b7f0b3d9001a7e5d04",
  "app_id": "6820f3a4e7b91d003c45a1f2",
  "flow_id": "68a1c2e4f0b3d9001a7e5c21",
  "flow_goal": "Sign up, create a project called Launch, and check that it appears on the dashboard.",
  "flow_role": "admin",
  "site_url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA",
  "status": "success",
  "actions": [
    {
      "step_summary": "Clicked Sign up in the header to reach the registration form.",
      "step_title": "Opened the sign-up form"
    }
  ],
  "result_message": "Created the project and found it on the dashboard.",
  "goal_accomplished": true,
  "live_status": "Analyzing results",
  "analysis_status": "completed",
  "failure_reason": "app",
  "credits_charged": 1.5,
  "started_at": "2026-09-28T10:16:02+00:00",
  "completed_at": "2026-09-28T10:18:40+00:00",
  "created_date": "2026-09-28T10:16:00+00:00",
  "updated_date": "2026-09-28T10:18:40+00:00"
}