--- title: "Execute browser action" method: POST path: "/browser_sessions/{id}/actions" tags: ["Actions"] --- # Execute browser action `POST /browser_sessions/{id}/actions` ## Request - Base URL: `https://api.telnyx.com/v2` - URL: `https://api.telnyx.com/v2/browser_sessions/{id}/actions` - Auth: HTTP bearer Executes a browser action on the session. Returns 200 if completed within wait_seconds, 202 if still in-flight. Action types: navigate, observe, click, fill, select, press, scroll, wait_for, screenshot, batch. ## Path parameters - `id` string, required ## Query parameters - `wait_seconds` integer ## Request body - union: Discriminated union on type. Variants are strict: unknown fields are rejected with 400. Reusing an idempotency_key with an identical request replays the original resource; with a different request it returns 409 idempotency_conflict. - NavigateAction: Navigate to a URL. - `type` 'navigate', required - `url` string, uri, required - `wait_until` 'load' | 'dom_stable' | 'none' - `include_observation` boolean - `idempotency_key` string - ObserveAction: Capture an observation (DOM snapshot) of the current page. - `type` 'observe', required - `include_observation` boolean - `idempotency_key` string - ClickAction: Click an element identified by observation_id + ref. - `type` 'click', required - `observation_id` string, required - `ref` string, required - `wait` 'no_wait' | 'dom_stable' | 'url_change' - `timeout_ms` integer - `include_observation` boolean - `idempotency_key` string - FillAction: Type text into the element identified by observation_id + ref. - `type` 'fill', required - `observation_id` string, required - `ref` string, required - `value` string, required - `include_observation` boolean - `idempotency_key` string - SelectAction: Select an option on the element identified by observation_id + ref. - `type` 'select', required - `observation_id` string, required - `ref` string, required - `value` string, required - `include_observation` boolean - `idempotency_key` string - PressAction: Press a keyboard key. - `type` 'press', required - `key` 'Enter' | 'Tab' | 'Escape' | 'Backspace' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'PageUp' | 'PageDown' | 'Home' | 'End', required - `include_observation` boolean - `idempotency_key` string - ScrollAction: Scroll the page. - `type` 'scroll', required - `delta_x` integer - `delta_y` integer - `include_observation` boolean - `idempotency_key` string - ScreenshotAction: Capture a screenshot of the current page. - `type` 'screenshot', required - `include_observation` boolean - `idempotency_key` string - WaitForAction: Wait for a condition before continuing. - `type` 'wait_for', required - `condition` union, required - object - `kind` 'url_pattern', required - `pattern` string, required - object - `kind` 'ref', required - `observation_id` string, required - `ref` string, required - object - `kind` 'text', required - `text` string, required - object - `kind` 'dom_stable', required - `timeout_ms` integer - `include_observation` boolean - `idempotency_key` string - BatchAction: Execute 1-50 sub-actions sequentially. Non-recursive: a batch inside a batch is rejected (400). An empty array is rejected (400). A failed sub-action stops the batch; earlier browser mutations are not rolled back, but partial sub-action results are not returned. - `type` 'batch', required - `actions` union[], required - union - NavigateAction: Navigate to a URL. - `type` 'navigate', required - `url` string, uri, required - `wait_until` 'load' | 'dom_stable' | 'none' - `include_observation` boolean - `idempotency_key` string - ObserveAction: Capture an observation (DOM snapshot) of the current page. - `type` 'observe', required - `include_observation` boolean - `idempotency_key` string - ClickAction: Click an element identified by observation_id + ref. - `type` 'click', required - `observation_id` string, required - `ref` string, required - `wait` 'no_wait' | 'dom_stable' | 'url_change' - `timeout_ms` integer - `include_observation` boolean - `idempotency_key` string - FillAction: Type text into the element identified by observation_id + ref. - `type` 'fill', required - `observation_id` string, required - `ref` string, required - `value` string, required - `include_observation` boolean - `idempotency_key` string - SelectAction: Select an option on the element identified by observation_id + ref. - `type` 'select', required - `observation_id` string, required - `ref` string, required - `value` string, required - `include_observation` boolean - `idempotency_key` string - PressAction: Press a keyboard key. - `type` 'press', required - `key` 'Enter' | 'Tab' | 'Escape' | 'Backspace' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'PageUp' | 'PageDown' | 'Home' | 'End', required - `include_observation` boolean - `idempotency_key` string - ScrollAction: Scroll the page. - `type` 'scroll', required - `delta_x` integer - `delta_y` integer - `include_observation` boolean - `idempotency_key` string - ScreenshotAction: Capture a screenshot of the current page. - `type` 'screenshot', required - `include_observation` boolean - `idempotency_key` string - WaitForAction: Wait for a condition before continuing. - `type` 'wait_for', required - `condition` union, required - object - … - object - … - object - … - object - … - `timeout_ms` integer - `include_observation` boolean - `idempotency_key` string - `include_observation` boolean - `idempotency_key` string ## Response `200` Terminal action: succeeded, failed, or unknown. Inspect data.status and data.error; HTTP 200 does not imply successful execution. - object - `data` ActionResponse - `id` string, required - `session_id` string, required - `seq` integer, required - `type` string, required - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown', required: POST returns 202 for queued or running actions. Terminal states are succeeded, failed, and unknown (the execution outcome could not be determined, with error.code=execution_lost). GET returns 200 for both nonterminal and terminal states. - `result` object, nullable, required - `url` string - `title` string - `observation` object: Full tree and refs are delivered only in the original successful POST response when completed within wait_seconds. GET polling and idempotent replays return metadata with an empty tree and refs plus ref_count. Submit a fresh observe action to obtain usable refs. - `observation_id` string - `url` string - `title` string - `refs` object - `tree` string - `truncated` boolean - `ref_count` integer: Number of refs in the original observation, present on stored observation metadata. - `artifact` object - `artifact_id` string - `content_type` string - `size_bytes` integer - `results` object[]: Present only for batch actions. - `request` object, required: Normalized request metadata; defaults may be materialized and fill values are redacted as {redacted: true, length: number}, including inside batch actions. - `error` object, nullable, required: Null unless an execution failure is recorded. Action failures (policy_denied, stale_observation, stale_ref, navigation_blocked, timeout, execution_lost, result_too_large) are returned on the action resource with HTTP 200. An unknown action with execution_lost has retryable=false; inspect session state and reconcile possible effects before any new action. Separately, a request may return HTTP 503 with a top-level execution_lost error and retryable=true; that is not proof of safe re-execution. - `code` string, required - `retryable` boolean, required - `created_at` string, date-time, required - `started_at` string, date-time, nullable, required - `completed_at` string, date-time, nullable, required ## Other responses - `202`: Action still in-flight — poll for result - `400`: Invalid request — validation error or invalid parameters. - `401`: Unauthorized — missing or invalid API key. - `404`: Session or artifact not found. - `409`: session_not_ready: new actions require a ready session; poll while provisioning, but do not retry new actions on closing or terminal sessions. concurrent_action: wait for the in-flight action. idempotency_conflict: the key was reused with a different normalized request. - `503`: The request could not be completed reliably. Retrieve action and session state before retrying; a mutation may already have taken effect. Do not blindly repeat it with a new idempotency key or session. ## Changes > 152 revisions in range; 1 not diffed. - **2026-10-22** `2961ffd5402d`: 1 info - endpoint added [Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/browser_sessions/:id/actions/post.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)