{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Run a template with the API"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"run-a-template-with-the-api","__idx":0},"children":["Run a template with the API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continue in the same Bash session and working directory as the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/browser-rpa/quickstart"},"children":["quickstart"]},". First check that the client supports the operations this page uses:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"jq -e '.data.operations as $ops | [\"validateWorkflow\",\"startRun\",\"getRun\",\"listRunNodes\",\"listRunArtifacts\"] - $ops | length == 0' capabilities.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose a Chromium browser profile. The environment ID is the profile's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envId"]},". If you only know the profile's name, find it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ml-cli env find --keyword <keyword>"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/env/page"]}," in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-reference/browser/local-api"},"children":["Browser Local API"]},", and resolve any ambiguity before you run. To confirm the browser type, check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/env/detail"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["browserTypeId: 1"]},". Pass the ID as a string. List positions and debug ports are not profile IDs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-preflight-the-saved-version","__idx":1},"children":["1. Preflight the saved version"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the same template ID, version, environment, and parameters for the preflight and the run. Supply each parameter value as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{kind:\"json\",value:...}"]},". Private parameters are sent as plaintext, and file parameters use absolute local paths (an array for multiple files). This example has no private parameters. Continue only when the validation report shows ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valid: true"]}," and is complete. If the profile is busy, wait until the previous run releases its isolation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":": \"${RPA_ENVIRONMENT_ID:?Set the actual Chromium profile ID first}\"\njq --arg env \"$RPA_ENVIRONMENT_ID\" '\n  .data | {templateId:.id,version,environmentId:$env,\n    parameters:{targetUrl:{kind:\"json\",value:\"https://example.com\"}}}\n' created.json > start-run.json &&\njq '{purpose:\"run\",source:{kind:\"template\",templateId,version},\n    environmentId,parameters}' start-run.json > validate-run.json &&\nrpa_curl \"$RPA_BASE_URL/validations\" -H 'Content-Type: application/json' --data-binary @validate-run.json -o validation-run.json &&\njq '.data | {valid,issues,truncated,runtimeChecks}' validation-run.json &&\njq -e '.data.valid == true and .data.truncated == false' validation-run.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-start-the-run","__idx":2},"children":["2. Start the run"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"([ -s run.key ] || uuidgen > run.key) &&\nrpa_curl \"$RPA_BASE_URL/runs\" \\\n  -H 'Content-Type: application/json' \\\n  -H \"X-RPA-Catalog-Revision: $RPA_CATALOG_REVISION\" \\\n  -H \"Idempotency-Key: $(cat run.key)\" \\\n  --data-binary @start-run.json -o started.json &&\nRPA_RUN_ID=\"$(jq -er '.data.id' started.json)\" &&\njq '.data | {id,status,template}' started.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["HTTP 202 means the run is registered, not finished. Keep the run ID, the original key, and the frozen template revision. A transport timeout doesn't cancel the run: use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/browser-rpa/local-api#recovery"},"children":["request recovery"]}," before you send another write."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-wait-for-a-terminal-state","__idx":3},"children":["3. Wait for a terminal state"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"for attempt in $(seq 1 100); do\n  rpa_curl \"$RPA_BASE_URL/runs/$RPA_RUN_ID\" -o run-detail.json || break\n  status=\"$(jq -r '.data.run.status' run-detail.json)\"\n  echo \"status: $status\"\n  case \"$status\" in\n    success|failed|cancelled|stopped|missed) break ;;\n    queued) sleep 5 ;;\n    *) sleep 3 ;;\n  esac\ndone\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The loop checks an active run every 3 seconds and a queued run every 5 seconds, and gives up after 100 checks. Active states are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["queued"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preparing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["running"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancel_requested"]},". Terminal states are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stopped"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missed"]},". Keep all observation requests within 40 per minute, and honor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," on 429 or 503."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-read-the-result","__idx":4},"children":["4. Read the result"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"jq '.data | {status:.run.status,hasNodeErrors:.run.hasNodeErrors,\n             isolation:.run.isolation,outputs:.result.outputs,error:.result.error}' run-detail.json &&\nrpa_curl \"$RPA_BASE_URL/runs/$RPA_RUN_ID/nodes?page=1&pageSize=20\" -o run-nodes.json &&\nrpa_curl \"$RPA_BASE_URL/runs/$RPA_RUN_ID/artifacts\" -o run-artifacts.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The example returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputs.result: \"https://example.com/\""]},". Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.run.hasNodeErrors"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.run.isolation.state"]},", and both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result.outputs"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result.error"]},": a run can succeed while some nodes failed and were skipped."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Node execution records are paged. While a run is active, read from page 1 on each pass and merge by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items[].id"]},". After the run reaches a terminal state, read all pages without a status filter. The artifacts endpoint returns metadata only. Redact sensitive output before you share it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cancellation is a request: keep checking the actual terminal state and the isolation state. Don't restart automatically when the outcome is uncertain or the environment is still quarantined. For details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/browser-rpa/api/get-run"},"children":["Get run details"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/browser-rpa/api/list-run-nodes"},"children":["List node executions"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/browser-rpa/api/observation"},"children":["Run observation and request recovery"]},"."]}]},"headings":[{"value":"Run a template with the API","id":"run-a-template-with-the-api","depth":1},{"value":"1. Preflight the saved version","id":"1-preflight-the-saved-version","depth":2},{"value":"2. Start the run","id":"2-start-the-run","depth":2},{"value":"3. Wait for a terminal state","id":"3-wait-for-a-terminal-state","depth":2},{"value":"4. Read the result","id":"4-read-the-result","depth":2}],"frontmatter":{"seo":{"title":"Run a template with the API"}},"lastModified":"2026-11-20T14:40:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/browser-rpa/run-api-example","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}