Run test

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/testing-agent/executions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "68a1c2e4f0b3d9001a7e5c21",
  "url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/testing-agent/executions"

payload = {
    "flow_id": "68a1c2e4f0b3d9001a7e5c21",
    "url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '68a1c2e4f0b3d9001a7e5c21',
    url: 'https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA'
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/testing-agent/executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/testing-agent/executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow_id' => '68a1c2e4f0b3d9001a7e5c21',
    'url' => 'https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/testing-agent/executions"

	payload := strings.NewReader("{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/testing-agent/executions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/testing-agent/executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error": {
    "code": "database_unavailable",
    "message": "Database temporarily unavailable, please retry",
    "details": {}
  }
}

Testing

Run test

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

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.

POST

api

apps

{app_id}

testing-agent

executions

Run test

curl --request POST \
  --url https://app.base44.com/api/apps/{app_id}/testing-agent/executions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "68a1c2e4f0b3d9001a7e5c21",
  "url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"
}
'

import requests

url = "https://app.base44.com/api/apps/{app_id}/testing-agent/executions"

payload = {
    "flow_id": "68a1c2e4f0b3d9001a7e5c21",
    "url": "https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '68a1c2e4f0b3d9001a7e5c21',
    url: 'https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA'
  })
};

fetch('https://app.base44.com/api/apps/{app_id}/testing-agent/executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.base44.com/api/apps/{app_id}/testing-agent/executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow_id' => '68a1c2e4f0b3d9001a7e5c21',
    'url' => 'https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.base44.com/api/apps/{app_id}/testing-agent/executions"

	payload := strings.NewReader("{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.base44.com/api/apps/{app_id}/testing-agent/executions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.base44.com/api/apps/{app_id}/testing-agent/executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow_id\": \"68a1c2e4f0b3d9001a7e5c21\",\n  \"url\": \"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error": {
    "code": "database_unavailable",
    "message": "Database temporarily unavailable, please retry",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Personal access token, sent as Authorization: Bearer <token>. Each operation lists the permission it needs: read_only or full_access. A full-access token can call every operation. A read-only token can call only the operations that list read_only; anything else returns 403 read_only_credential_route_not_allowed.

Scopes

full_access

Path Parameters

app_id

string

required

ID of the app.

Body

application/json

flow_id

string

required

ID of the test to run.

Example:

"68a1c2e4f0b3d9001a7e5c21"

url

string | null

Page the run starts on. Leave it out to start on the app's current preview.

Maximum string length: 2000

Example:

"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"

Response

The queued run.

One run of a test.

string

required

ID of the run.

Example:

"68a1c9b7f0b3d9001a7e5d04"

app_id

string

required

ID of the app.

Example:

"6820f3a4e7b91d003c45a1f2"

flow_id

string

required

ID of the test this run belongs to.

Example:

"68a1c2e4f0b3d9001a7e5c21"

flow_goal

string

required

The test's goal when the run started.

Example:

"Sign up, create a project called Launch, and check that it appears on the dashboard."

flow_role

string | null

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.

Example:

"admin"

site_url

string

required

URL the run opened.

Example:

"https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA"

status

enum<string>

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.

Available options:

pending,

running,

analyzing,

success,

failed,

timeout,

cancelled,

paused

Example:

"success"

actions

TestRunStep · object[]

required

Steps the agent took. Empty until the run finishes.

Show child attributes

Example:

[
  {
    "step_summary": "Clicked Sign up in the header to reach the registration form.",
    "step_title": "Opened the sign-up form"
  }
]

result_message

string | null

required

The agent's account of how the run went, or null before the run finishes.

Example:

"Created the project and found it on the dashboard."

goal_accomplished

boolean | null

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.

Example:

true

live_status

string | null

required

Short progress message for display, or null before the run starts.

Example:

"Analyzing results"

analysis_status

enum<string> | null

required

Progress of the run's report. completed means Get test run report has it. null before the run reaches analysis.

Available options:

pending,

completed,

failed

Example:

"completed"

failure_reason

enum<string> | null

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.

Available options:

app,

platform,

internal,

out_of_credits

Example:

"app"

credits_charged

number | null

required

Credits the run cost, or null before it's charged.

Example:

1.5

started_at

string | null

required

When the browser session started, as an ISO 8601 UTC timestamp, or null while pending.

Example:

"2026-09-28T10:16:02+00:00"

completed_at

string | null

required

When the run ended, as an ISO 8601 UTC timestamp, or null while it's still going.

Example:

"2026-09-28T10:18:40+00:00"

created_date

string

required

When the run was requested, as an ISO 8601 UTC timestamp.

Example:

"2026-09-28T10:16:00+00:00"

updated_date

string

required

When the run last changed, as an ISO 8601 UTC timestamp.

Example:

"2026-09-28T10:18:40+00:00"

Base44 APIs

Apps API (Beta)

Workspace API (Beta)

Superagents API (Beta)

Monitoring API

Audit Logs API

Compliance API

Outbound webhooks

Run test

Authorizations

Scopes

Path Parameters

Body

Response