SPHYNX
esc
  • Loading
Open console

Guides

Screenshots

Capture the viewport, the full page or one element, with or without a session.

At the end you have an image file of a page as the hosted browser rendered it. You need an API key. The first sections use a running session. The last one needs no session.

Before you start

The snippets read the base URL and the key from the environment and keep the session ID in SESSION. start_url is loaded before the create call returns.

Shell
export SPHYNX_URL=http://localhost:8080   # your deployment's base URL
export SPHYNX_API_KEY=sx_live_...

SESSION=$(curl -s -X POST "$SPHYNX_URL/v1/sessions" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_url": "https://example.com"}' | jq -r .id)

Capture the viewport

POST/v1/sessions/{id}/screenshot with an empty body captures what is on screen as a JPEG. The image comes back base64-encoded in image_base64.

curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/screenshot" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .image_base64 | base64 -d > page.jpg
200
{
  "format": "jpeg",
  "image_base64": "/9j/4AAQ..."
}

Capture the full page

Set full_page to true to capture the whole scrollable page, not only the viewport. The capture stops at 16384 CSS px per side: a longer page is captured from its top left.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/screenshot" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_page": true, "format": "png"}' \
  | jq -r .image_base64 | base64 -d > page.png

Capture one element

Pass a selector or an xpath to capture a single element, not both. The first match is used. An element is captured up to 16384 CSS px per side, from its top left.

curl
curl -s -X POST "$SPHYNX_URL/v1/sessions/$SESSION/screenshot" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selector": "p", "format": "png"}' \
  | jq -r .image_base64 | base64 -d > paragraph.png

The same element by XPath takes this body:

Body
{ "xpath": "//p", "format": "png" }

Choose the format

format is jpeg or png. JPEG is the default, at quality 70. quality runs from 1 to 100 and applies to JPEG only.

Body
{ "format": "jpeg", "quality": 90 }

Calls without tab_id capture the active tab. Pass tab_id to capture another one.

Without a session

POST/v1/screenshot takes a URL and returns an image. There is no session to create or clean up. It accepts the same capture fields, plus os, proxy, wait_until and timeout_ms for the browser and the page load.

curl -s -X POST "$SPHYNX_URL/v1/screenshot" \
  -H "Authorization: Bearer $SPHYNX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "full_page": true}' \
  | jq -r .image_base64 | base64 -d > example.jpg

The response also says where the browser ended up. http_status is the status of the main document: a site's own 403 or 404 page is still a 200 response here, so check it.

200
{
  "url": "https://example.com/",
  "title": "Example Domain",
  "http_status": 200,
  "format": "jpeg",
  "image_base64": "/9j/4AAQ..."
}

What can go wrong

Session screenshots:

HTTPCodeWhen
400invalid_requestUnknown field, a bad value, a bad selector or XPath, or both selector and xpath
404element_not_foundNo element matched selector or xpath
409no_page_loadedThe tab is blank. Navigate first
409session_in_useAnother drive call has been running on this session for more than 3 s. Retry
410session_closedThe session has ended

The stateless call can also fail the way creating a session or loading a page can:

HTTPCodeWhen
422unsafe_urlNot http or https, or a private, loopback or link-local address
429concurrency_limitToo many live sessions for this key. Retry-After is set
502navigation_failedDNS failure, connection refused, TLS error
503capacity_unavailableNo browser capacity. Retry-After is set
504navigation_timeoutThe page did not reach wait_until in timeout_ms

Next