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.
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.jpgimport { writeFile } from "node:fs/promises";
const url = `${process.env.SPHYNX_URL}/v1/sessions/${sessionId}/screenshot`;
const res = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
const { image_base64 } = await res.json();
await writeFile("page.jpg", Buffer.from(image_base64, "base64"));import base64
import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/sessions/{session_id}/screenshot",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={},
timeout=60,
)
with open("page.jpg", "wb") as image:
image.write(base64.b64decode(res.json()["image_base64"])){
"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 -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.pngCapture 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 -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.pngThe same element by XPath takes this 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.
{ "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.jpgimport { writeFile } from "node:fs/promises";
const res = await fetch(`${process.env.SPHYNX_URL}/v1/screenshot`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SPHYNX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://example.com", full_page: true }),
});
const shot = await res.json();
await writeFile("example.jpg", Buffer.from(shot.image_base64, "base64"));import base64
import os
import requests
res = requests.post(
f"{os.environ['SPHYNX_URL']}/v1/screenshot",
headers={"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}"},
json={"url": "https://example.com", "full_page": True},
timeout=90,
)
shot = res.json()
with open("example.jpg", "wb") as image:
image.write(base64.b64decode(shot["image_base64"]))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.
{
"url": "https://example.com/",
"title": "Example Domain",
"http_status": 200,
"format": "jpeg",
"image_base64": "/9j/4AAQ..."
}What can go wrong
Session screenshots:
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Unknown field, a bad value, a bad selector or XPath, or both selector and xpath |
| 404 | element_not_found | No element matched selector or xpath |
| 409 | no_page_loaded | The tab is blank. Navigate first |
| 409 | session_in_use | Another drive call has been running on this session for more than 3 s. Retry |
| 410 | session_closed | The session has ended |
The stateless call can also fail the way creating a session or loading a page can:
| HTTP | Code | When |
|---|---|---|
| 422 | unsafe_url | Not http or https, or a private, loopback or link-local address |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set |
| 502 | navigation_failed | DNS failure, connection refused, TLS error |
| 503 | capacity_unavailable | No browser capacity. Retry-After is set |
| 504 | navigation_timeout | The page did not reach wait_until in timeout_ms |
Next
- Screenshot: every field of the session call.
- Stateless screenshot: every field of the one-call version.
- Proxies: capture a page as seen from another country.