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
- urlstringrequired
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.
- 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.
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 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,
proxy: { type: "residential", country: "gb" },
}),
});
const { image_base64 } = await res.json();
await writeFile("example.jpg", Buffer.from(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,
"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 session create errors apply, because the call starts a browser. 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 |
| 401 | unauthorized | Missing or invalid API key |
| 404 | element_not_found | No element matched selector or xpath |
| 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, or is a private, loopback or link-local address |
| 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 | DNS failure, connection refused, TLS error |
| 503 | capacity_unavailable | The host is full. Retry-After is set |
| 503 | residential_unavailable | Residential proxy is not configured or not reachable |
| 504 | navigation_timeout | The page did not reach wait_until in timeout_ms |