SPHYNX
esc
  • Loading
Open console

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.

POST/v1/sessions/{id}/navigate

Returns 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 200 API response. A navigation that only changes the #fragment of the page the tab is on loads nothing: http_status is then the status that page was loaded with, or 0 when 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_ms leaves: the result is then that page, with its http_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"}'
200
{
  "url": "https://news.ycombinator.com/",
  "title": "Hacker News",
  "http_status": 200,
  "redirected": false
}
Body · every field
{
  "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.

502
{
  "error": {
    "code": "navigation_failed",
    "message": "the page could not be loaded",
    "request_id": "req_5d1c0e7a9b3f"
  }
}
200 · GET /tabs afterwards
{
  "data": [
    {
      "tab_id": "8B1F6C0A2D3E4F5A9B7C1D0E2F3A4B5C",
      "url": "http://nope.invalid/",
      "title": "nope.invalid"
    }
  ]
}

Errors

The shape is the same as everywhere else: see Errors.

HTTPCodeWhen
400invalid_requestMalformed JSON, unknown field, bad value
401unauthorizedMissing or invalid API key
404session_not_foundNo such session for this key
404tab_not_foundNo such tab
409session_in_useAnother drive call has been running on this session for more than 3 s
410session_closedThe session has ended
422unsafe_urlNot http/https, longer than 2048 characters, or a private, loopback or link-local address in the URL
500internalOur fault. Send us the request_id
502navigation_failedThe 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)
504navigation_timeoutThe page did not reach wait_until in timeout_ms