Skip to content
Browsa
  1. Guides
  2. Recipes

Recipes: record a task once, replay it

A recipe is a saved browser job with inputs, steps and an output schema. Run it again with new inputs and get JSON back in seconds, on Phantom, with no model in the loop when nothing changed.

Create a recipe from a task

Run any agent task with record_recipe: true. When the job finishes it carries a recipe_draft_id. Save it as a recipe and give it a name.

Terminal
curl https://browsa.io/v1/tasks -H "X-API-Key: $BROWSA_API_KEY" \
  -d '{"task": "Search walmart.com for coffee maker, return title and price of each result",
       "llm": "browsa", "record_recipe": true,
       "output_schema": {"type": "object", "properties": {"items": {"type": "array"}}, "required": ["items"]}}'

# when the job is completed
curl https://browsa.io/v1/recipes -H "X-API-Key: $BROWSA_API_KEY" \
  -d '{"from_job_id": "JOB_ID", "name": "walmart-search"}'

Browsa turns the run into steps. Calls the page made to the site's own JSON endpoints become network steps; clicks, typing and reads become DOM steps with several locators each. Browsa proposes the parameters (here the search term). Check them with GET /v1/recipes/{id}, and pass params or output on create to set them yourself.

Or upload one

A recipe is plain JSON. Write it by hand or edit a recorded one, then POST /v1/recipes with {"recipe": {...}}. It is checked against the recipe schema (recipe-v1) before it is saved.

quotes.json
{
  "name": "quotes",
  "version": 1,
  "params": { "type": "object", "properties": { "page": { "type": "integer", "default": 1 } } },
  "output": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1 } }, "required": ["items"] },
  "exit": { "network": "default" },
  "steps": [
    { "id": "s1", "kind": "navigate", "url": "https://quotes.toscrape.com/page/{{page}}/" },
    { "id": "s2", "kind": "fetch", "in_page": true, "method": "GET", "mutation": false, "save_as": "quotes",
      "url": "https://quotes.toscrape.com/api/quotes?page={{page}}" },
    { "id": "s3", "kind": "extract", "from": "saved", "source": "quotes", "schema_ref": "output",
      "how": { "jsonpath": "$.quotes[*]" } },
    { "id": "s4", "kind": "extract", "from": "page", "schema_ref": "output",
      "how": { "css": "div.quote", "fields": { "text": "span.text", "author": "small.author" } } }
  ],
  "fallbacks": { "s2": ["s4"] }
}
  • Step kinds. navigate, click, type, select, press, scroll, wait, fetch, extract, assert.
  • Placeholders. {{param}}, {{json:param}} for a JSON value, {{discover:key}} for a value read from the page at run time.
  • Fallbacks. The steps that run instead when a step fails. Here the DOM read replaces the network call.
  • Writes. A fetch that changes something must say mutation: true. It is sent only when your recipe says so.

Run it with new inputs

Terminal
curl https://browsa.io/v1/recipes/RECIPE_ID/run -H "X-API-Key: $BROWSA_API_KEY" \
  -d '{"params": {"query": "air fryer"}, "wait": 60}'

With wait the call returns the finished run. Without it you get a run id at once; read it with GET /v1/recipe-runs/{run_id} or pass webhook_url. A run returns status, output, the layer each step used, whether a repair ran, duration_ms and credits. You can also pass proxy and profile_id, as on a task, and schedule a recipe with recipe_id and params.

Each step tries three layers in order:

  1. Network, inside the page. The site's own JSON call, sent from a live Phantom page with its cookies and fingerprint.
  2. DOM. If the call fails or its answer does not fit, the fallback steps run. Captchas are solved in the session, as in tasks.
  3. One-step repair. If a DOM step fails, the agent gets that one goal on the current page, with a small step budget. Its action becomes the new step.
  4. Check. The output must match your output schema and assertions, or the run fails.

Versions, promote, rollback

A repair never changes the live version on the spot. It saves a draft version. The draft becomes live only after a full run with it passes and its output validates.

repair_mode: "auto"
Default. A draft that passes its check run is promoted.
repair_mode: "review"
Drafts wait for you: POST /v1/recipes/{id}/versions/{v}/promote.
List versions
GET /v1/recipes/{id}/versions
Roll back
POST /v1/recipes/{id}/rollback makes the previous version live again.
Webhooks
recipe.repaired, recipe.promoted, recipe.failed

Failures

A failed run is typed and free. If a browser had started, its time is refunded as with tasks.

CodeWhat happenedWhat to do
blockedA bot wall was not passedTry another exit (proxy). See the per-site numbers
needs_loginThe site asked to sign inSign in again on the profile, then rerun
site_changedA step broke and the repair did not fix itRecord the task again; the live version is unchanged
invalid_outputThe data did not match the output schemaCheck the schema, or record again
params_invalidThe inputs did not match the params schemaFix the request
timeoutThe run took longer than its budgetRerun, or raise wait

Pricing

A replay costs the same credits as the task it was recorded from. Failed replays are free. What you gain is time: seconds instead of a minute, and the same steps and output on every run.

Next steps

Record your first recipe.

100 free credits. No card, no subscription.