Skip to main content
POST
/
browser
/
sessions
/
{id}
/
navigate
Navigate
curl --request POST \
  --url https://api.example.com/browser/sessions/{id}/navigate \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "waitUntil": "<string>",
  "timeout": 123,
  "referer": "<string>"
}
'
{
  "url": "<string>",
  "pageId": "<string>"
}

​
Overview

The /browser/sessions/{id}/navigate endpoint navigates the currently active tab of a browser session to the given URL and blocks until the configured wait condition is met or the timeout elapses. Only http and https URLs are accepted. The navigation is scoped to the active tab — use POST /pages/{pageId}/activate to switch active tabs first.

​
Path Parameters

​
id
string
required
Browser session ID (UUID). Create via POST /browser/sessions.

​
Body

​
url
string
required
Absolute URL to navigate to. Must use the http or https scheme.
​
waitUntil
string
default:"load"
When to consider the navigation finished. One of load, domcontentloaded, networkidle.
​
timeout
integer
default:"30000"
Maximum time (ms) to wait for navigation. Range 0–120000.
​
referer
string
Optional Referer header sent with this navigation request only. Does not persist to subsequent navigations.

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/navigate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

​
Response

​
Success Response (200)

​
url
string
Effective URL of the active tab after all redirects.
​
pageId
string
CDP target identifier of the tab the navigation applied to.
Example Response: 
{
  "url": "https://example.com/",
  "pageId": "EA5E9AA71C7A91C467F8CDBB266EE5E0"
}

​
Error Responses

StatusDescription
400Invalid body — malformed URL, non-http(s) scheme, or unknown waitUntil value.
401Unauthorized — invalid or missing API key.
404Session not found or not owned by the caller.
408Navigation did not complete before timeout elapsed.
503The browser session is temporarily unreachable.

​
Notes

  • waitUntil=load waits for document.readyState === "complete". domcontentloaded returns once the DOM parser finishes. networkidle waits for 500ms of no network activity (best-effort, capped at 10s).
  • referer is per-request and does not persist to subsequent navigations.