> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/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.

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



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/testing-agent/executions
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/testing-agent/executions:
    post:
      summary: Run test
      description: >-
        <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](/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.


        <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>
      operationId: run_flow_api_apps__app_id__testing_agent_executions_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app.
            title: App Id
          description: ID of the app.
          example: 6820f3a4e7b91d003c45a1f2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: RunTest
              required:
                - flow_id
              properties:
                flow_id:
                  type: string
                  description: ID of the test to run.
                  example: 68a1c2e4f0b3d9001a7e5c21
                url:
                  type: string
                  maxLength: 2000
                  description: >-
                    Page the run starts on. Leave it out to start on the app's
                    current preview.
                  example: >-
                    https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA
      responses:
        '200':
          description: The queued run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestRun'
        '400':
          description: >-
            `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':
          description: Missing or invalid credentials.
        '403':
          description: >-
            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':
          description: App or test not found.
        '409':
          description: >-
            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':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    TestRun:
      properties:
        id:
          type: string
          title: Id
          description: ID of the run.
          example: 68a1c9b7f0b3d9001a7e5d04
        app_id:
          type: string
          title: App Id
          description: ID of the app.
          example: 6820f3a4e7b91d003c45a1f2
        flow_id:
          type: string
          title: Flow Id
          description: ID of the test this run belongs to.
          example: 68a1c2e4f0b3d9001a7e5c21
        flow_goal:
          type: string
          title: Flow Goal
          description: 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:
          anyOf:
            - type: string
            - type: 'null'
          title: Flow Role
          description: >-
            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:
          type: string
          title: Site Url
          description: URL the run opened.
          example: >-
            https://preview-6820f3a4e7b91d003c45a1f2.base44.app/?_preview_token=FH-j7wHS7IR_fC1tUh4wCd_fNV1XGC479cuqNSYi9mA
        status:
          type: string
          enum:
            - pending
            - running
            - analyzing
            - success
            - failed
            - timeout
            - cancelled
            - paused
          title: Status
          description: >-
            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`.
          example: success
        actions:
          items:
            $ref: '#/components/schemas/TestRunStep'
          type: array
          title: Actions
          description: Steps the agent took. Empty until the run finishes.
          example:
            - step_summary: Clicked Sign up in the header to reach the registration form.
              step_title: Opened the sign-up form
        result_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Result Message
          description: >-
            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:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Goal Accomplished
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Live Status
          description: Short progress message for display, or `null` before the run starts.
          example: Analyzing results
        analysis_status:
          anyOf:
            - type: string
              enum:
                - pending
                - completed
                - failed
            - type: 'null'
          title: Analysis Status
          description: >-
            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.
          example: completed
        failure_reason:
          anyOf:
            - type: string
              enum:
                - app
                - platform
                - internal
                - out_of_credits
            - type: 'null'
          title: Failure Reason
          description: >-
            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`.
          example: app
        credits_charged:
          anyOf:
            - type: number
            - type: 'null'
          title: Credits Charged
          description: Credits the run cost, or `null` before it's charged.
          example: 1.5
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
          description: >-
            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:
          type: string
          title: Created Date
          description: When the run was requested, as an ISO 8601 UTC timestamp.
          example: '2026-09-28T10:16:00+00:00'
        updated_date:
          type: string
          title: Updated Date
          description: When the run last changed, as an ISO 8601 UTC timestamp.
          example: '2026-09-28T10:18:40+00:00'
      type: object
      required:
        - id
        - app_id
        - flow_id
        - flow_goal
        - flow_role
        - site_url
        - status
        - actions
        - result_message
        - goal_accomplished
        - live_status
        - analysis_status
        - failure_reason
        - credits_charged
        - started_at
        - completed_at
        - created_date
        - updated_date
      title: TestRun
      description: One run of a test.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TestRunStep:
      properties:
        step_title:
          type: string
          title: Step Title
          description: Short description of the step.
          example: Opened the sign-up form
        step_summary:
          type: string
          title: Step Summary
          description: What the agent did in this step and why.
          example: Clicked Sign up in the header to reach the registration form.
      type: object
      required:
        - step_title
        - step_summary
      title: TestRunStep
      description: One step the testing agent took during a run.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: 'Personal access token, sent as `Authorization: Bearer <token>`.'

````