API reference
Navigate
Load a URL in a session and get the final address, title and HTTP status.
Navigate loads a page and waits for it. The call returns when the page reaches wait_until, or fails when timeout_ms passes first.
Navigate
POST/v1/sessions/{id}/navigateReturns 200 when the page loaded, whatever status the site answered with. Check http_status in the response.
Path
- idstringrequired
The session to drive.
Body
- urlstring, http or https, ≤2048required
The address to load.
- wait_untilload or domcontentloadeddefaultload
The page event to wait for.
- timeout_msint, ≤60000default30000
How long to wait for
wait_until. - tab_idstringdefaultthe active tab
The tab to load the page in. It is brought to the front first.
Response
- urlstring
The address of the page after redirects.
- titlestring
The title of the page.
- http_statusint
The status of the main document. A 403 or 404 page is still a
200API response. A navigation that only changes the#fragmentof the page the tab is on loads nothing:http_statusis then the status that page was loaded with, or0when that is not known, for example because the tab got there by a click or through a CDP client. - redirectedbool
Whether the navigation was redirected. When the page that was asked for is behind a "checking your browser" page, navigate waits for the page itself, for as long as
timeout_msleaves: the result is then that page, with itshttp_status. If the time runs out first, the result is the checking page as it stands.
curl -s -X POST \
"$SPHYNX_URL/v1/sessions/$SESSION/navigate" \
-H "Authorization: Bearer $SPHYNX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://news.ycombinator.com"}'const base = process.env.SPHYNX_URL;
const endpoint = `${base}/v1/sessions/${sessionId}/navigate`;
const res = await fetch(endpoint, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://news.ycombinator.com",
}),
});
const page = await res.json();import os
import requests
base = os.environ["SPHYNX_URL"]
headers = {
"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}",
}
res = requests.post(
f"{base}/v1/sessions/{session_id}/navigate",
headers=headers,
json={"url": "https://news.ycombinator.com"},
timeout=60,
)
page = res.json(){
"url": "https://news.ycombinator.com/",
"title": "Hacker News",
"http_status": 200,
"redirected": false
}{
"url": "https://news.ycombinator.com",
"wait_until": "domcontentloaded",
"timeout_ms": 15000,
"tab_id": "TAB_ID"
}When a page does not load
A page that does not load fails the call with 502 navigation_failed, for http:// and https:// alike:
- the name does not resolve,
- the connection is refused or reset,
- TLS fails,
- the name resolves to an address the session may not reach: private, loopback, link-local or the host's own,
- the page sends the tab on, from script or with a meta refresh, to a URL that does not load.
A host that does not answer at all fails after about 15 s.
Afterwards the tab is on the browser's error page. List tabs shows the URL that failed, and Extract reports chrome-error://chromewebdata/.
A response with nothing to show, such as a 204 or a download, is navigation_failed too. It fails at once, and the tab stays on the page it had.
With proxy.type residential or external, a plain http:// host that cannot be reached is answered by the proxy itself. The call then returns 200 with the proxy's status, often 502 or 503, and the proxy's error page. https:// hosts answer navigation_failed there as well.
A private, loopback or link-local address written in the URL is refused before anything loads, with 422 unsafe_url.
{
"error": {
"code": "navigation_failed",
"message": "the page could not be loaded",
"request_id": "req_5d1c0e7a9b3f"
}
}{
"data": [
{
"tab_id": "8B1F6C0A2D3E4F5A9B7C1D0E2F3A4B5C",
"url": "http://nope.invalid/",
"title": "nope.invalid"
}
]
}Errors
The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, bad value |
| 401 | unauthorized | Missing or invalid API key |
| 404 | session_not_found | No such session for this key |
| 404 | tab_not_found | No such tab |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s |
| 410 | session_closed | The session has ended |
| 422 | unsafe_url | Not http/https, longer than 2048 characters, or a private, loopback or link-local address in the URL |
| 500 | internal | Our fault. Send us the request_id |
| 502 | navigation_failed | The page did not load: DNS failure, connection refused or reset, TLS error, an address the session may not reach, a redirect from the page to a URL that does not load, or a response with nothing to show (204, download) |
| 504 | navigation_timeout | The page did not reach wait_until in timeout_ms |