API reference
Stateless screenshot
Send a URL, get an image. No session to create or clean up.
The call starts a browser for the request and closes it afterwards. It counts toward your concurrency limit while it runs and is metered like a session.
Take a stateless screenshot
POST/v1/screenshotLoads url, captures it and returns the image with what the page answered.
Body
- urlstring, ≤2048required
The address to capture.
- oswindows, mac or linuxdefaultrandom
Picks a fingerprint of that operating system.
- proxyobject
The same object as on session create.
- typenone, residential or externaldefaultnone
noneis direct datacenter egress. - countryISO 3166-1 alpha-2, lowercasedefaultus
residentialonly. - serverstring
externalonly, and required there.host:portorhttp(s)://host:port. - usernamestring
externalonly. - passwordstring
externalonly.
- wait_untilload or domcontentloadeddefaultload
The page event to wait for. As in Navigate.
- timeout_msint, ≤60000default30000
How long to wait for
wait_until. - full_pagebooldefaultfalse
Capture the whole page instead of the viewport. The capture stops at 16384 CSS px per side. Cannot be combined with
selectororxpath: that isinvalid_requestwithdetails.fieldfull_page. - selectorstring
Capture one element, found by CSS selector. At most 16384 CSS px per side, from its top left.
- xpathstring
Capture one element, found by XPath, with the same bound. Use
selectororxpath, not both. - formatjpeg or pngdefaultjpeg
The image format.
- qualityint, 1–100default70
JPEG quality.
jpegonly.0is the default.
Response
- urlstring
The address of the page after redirects.
- titlestring
The title of the page.
- http_statusint
The status of the main document.
- formatstring
jpegorpng. - image_base64string
The image, base64-encoded.
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,
"proxy": {"type": "residential", "country": "gb"}
}' | jq -r .image_base64 | base64 -d > example.jpgimport { writeFile } from "node:fs/promises";
const base = process.env.SPHYNX_URL;
const res = await fetch(`${base}/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,
proxy: { type: "residential", country: "gb" },
}),
});
const { image_base64 } = await res.json();
const image = Buffer.from(image_base64, "base64");
await writeFile("example.jpg", image);import base64
import os
import requests
base = os.environ["SPHYNX_URL"]
headers = {
"Authorization": f"Bearer {os.environ['SPHYNX_API_KEY']}",
}
res = requests.post(
f"{base}/v1/screenshot",
headers=headers,
json={
"url": "https://example.com",
"full_page": True,
"proxy": {"type": "residential", "country": "gb"},
},
timeout=90,
)
with open("example.jpg", "wb") as image:
image.write(base64.b64decode(res.json()["image_base64"])){
"url": "https://example.com/",
"title": "Example Domain",
"http_status": 200,
"format": "jpeg",
"image_base64": "/9j/4AAQ..."
}Errors
The call starts a browser and loads a page, so it can fail the way creating a session and navigating can. The shape is the same as everywhere else: see Errors.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed JSON, unknown field, bad value, both selector and xpath, full_page with either |
| 401 | unauthorized | Missing or invalid API key |
| 404 | element_not_found | No element matched selector or xpath |
| 410 | session_closed | The browser exited before the capture |
| 422 | unsupported_country | proxy.country is not in the proxy country list |
| 422 | proxy_invalid | Bad proxy object |
| 422 | unsafe_url | url is not http/https, is longer than 2048 characters, or has a private, loopback or link-local address in it |
| 429 | concurrency_limit | Too many live sessions for this key. Retry-After is set |
| 500 | internal | Our fault. Send us the request_id |
| 502 | proxy_unreachable | Could not connect through the proxy |
| 502 | session_launch_failed | The browser failed to start |
| 502 | navigation_failed | The url 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) |
| 503 | capacity_unavailable | The host is full. Retry-After is set |
| 503 | residential_unavailable | Residential proxy is not configured or not reachable. Retry-After is set |
| 504 | navigation_timeout | The page did not reach wait_until in timeout_ms |