Prompt Pilot

An Apify Actor that automates browser sessions using a declarative JSON step format. Steps are executed in order against a real browser (via Browserbase), using Stagehand AI for natural language interactions and direct Playwright selectors for deterministic actions.

---

Input

{
  "url": "https://example.com",
  "contextId": "optional-browserbase-context-id",
  "download": true,
  "model": "openai/gpt-5.2",
  "steps": [ ... ]
}

Field	Type	Required	Description
url	string	Yes	Starting page URL.
steps	Step[]	Yes	Ordered automation steps (see below).
download	boolean	No	Retrieve files downloaded during the session. Default: false.
contextId	string	No	Browserbase persistent context ID — reuses cookies/session across runs.
model	string	No	Stagehand AI model. Default: openai/gpt-5.2.

---

Step Types

Prompt (no action)

AI-driven interaction via stagehand.act(). Use natural language to describe the action.

{ "prompt": "Click the Search button." }

{
  "prompt": "Type %username% into the username field.",
  "variables": { "username": "alice@example.com" }
}

{
  "prompt": "Click the Submit button.",
  "waitFor": { "selector": ".confirmation-message" }
}

---

Navigate (action: "navigate")

Direct page navigation using page.goto().

{
  "action": "navigate",
  "url": "https://example.com/dashboard",
  "waitFor": { "selector": "#main-content" }
}

---

Select (action: "select")

Selects an option in a <select> element by its value attribute.

{
  "action": "select",
  "selector": "select[name='dateType']",
  "value": "3",
  "waitFor": { "selector": "#startDate" }
}

---

Click (action: "click")

Clicks an element directly using a CSS or XPath selector. Use inside a loop step with "$self" to click the current iteration's element.

{ "action": "click", "selector": "a.select2-choice" }

{ "action": "click", "selector": "xpath=//div[@class='result-label'][contains(text(),'%option%')]", "variables": { "option": "My Office" } }

---

Loop (action: "loop")

Iterates over all elements matching selector and runs steps for each one. Use "$self" in a nested click step to target the current element.

{
  "action": "loop",
  "selector": "a:has(i[title='Download'])",
  "steps": [
    { "action": "click", "selector": "$self" },
    {
      "action": "click",
      "selector": "xpath=//div[@class='dialog']//a[contains(text(),'Yes')]",
      "condition": { "selector": "xpath=//div[@class='dialog']//a[contains(text(),'Yes')]" }
    }
  ]
}

---

If (action: "if")

Executes the then branch if a selector is visible, otherwise executes the optional else branch.

{
  "action": "if",
  "condition": { "selector": "input[type='password']" },
  "then": [
    { "prompt": "Type %username% into the username field.", "variables": { "username": "alice" } },
    { "prompt": "Type %password% into the password field.", "variables": { "password": "secret" } },
    { "prompt": "Click the Log In button." }
  ],
  "else": [
    { "action": "navigate", "url": "https://example.com/account" }
  ]
}

---

API Request (action: "api-request")

Makes an HTTP request and stores a value extracted from the response for use in subsequent steps.

{
  "action": "api-request",
  "request": {
    "url": "https://api.example.com/messages?phone=%phone%",
    "method": "GET",
    "headers": { "Authorization": "%apiKey%" }
  },
  "resultExtract": {
    "jsonPath": "data[0].text",
    "regex": "code is (\\d{6})"
  },
  "resultVar": "mfaCode",
  "variables": { "phone": "+10000000000", "apiKey": "key_xxx" }
}

The extracted value is stored as %mfaCode% and available in all subsequent steps.

---

Condition and WaitFor

All step types (except if) support:

• condition.selector — skip this step if the selector is not visible when the step is about to execute.
• waitFor.selector — poll for this selector to become visible after the step completes. Throws on timeout.
• waitFor.timeout — polling timeout in ms. Default: 30000.

{
  "prompt": "Click the Continue button.",
  "condition": { "selector": "input[value='Continue']" },
  "waitFor": { "selector": "#dashboard", "timeout": 15000 }
}

---

Variable Substitution

%key% tokens in string fields are replaced before each step executes. Variables accumulate across steps via a shared context — values written by an api-request step are available to all later steps.

Auto-populated variables:

Variable	Value
%todayFormatted%	Today's date as MM/DD/YYYY.

---

Output

When download: true, files downloaded during the session are retrieved from Browserbase and stored in the Actor's Key-Value Store. One Dataset record is pushed per file:

{
  "success": true,
  "originalFileName": "payment_835.edi",
  "sanitizedFileName": "payment_835.edi",
  "fileSize": 4096,
  "timestamp": "2026-02-26T10:00:00.000Z"
}

On failure:

{
  "success": false,
  "error": "No files were downloaded",
  "timestamp": "2026-02-26T10:00:00.000Z"
}

---

Environment Variables

Set these in the Actor's environment configuration (not passed through input):

Variable	Description
BROWSERBASE_API_KEY	Browserbase API key.
BROWSERBASE_PROJECT_ID	Browserbase project ID.