SPHYNX
esc
  • Loading
Open console

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/screenshot

Loads 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

      none is direct datacenter egress.

    • countryISO 3166-1 alpha-2, lowercasedefaultus

      residential only.

    • serverstring

      external only, and required there. host:port or http(s)://host:port.

    • usernamestring

      external only.

    • passwordstring

      external only.

  • 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 selector or xpath, not both.

  • formatjpeg or pngdefaultjpeg

    The image format.

  • qualityint, 1–100default70

    JPEG quality. jpeg only.

Response

  • urlstring

    The address of the page after redirects.

  • titlestring

    The title of the page.

  • http_statusint

    The status of the main document.

  • formatstring

    jpeg or png.

  • 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.jpg
200
{
  "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.

HTTPCodeWhen
400invalid_requestMalformed JSON, unknown field, bad value, both selector and xpath
401unauthorizedMissing or invalid API key
404element_not_foundNo element matched selector or xpath
422unsupported_countryproxy.country is not in the proxy country list
422proxy_invalidBad proxy object
422unsafe_urlurl is not http/https, or is a private, loopback or link-local address
429concurrency_limitToo many live sessions for this key. Retry-After is set
500internalOur fault. Send us the request_id
502proxy_unreachableCould not connect through the proxy
502session_launch_failedThe browser failed to start
502navigation_failedDNS failure, connection refused, TLS error
503capacity_unavailableThe host is full. Retry-After is set
503residential_unavailableResidential proxy is not configured or not reachable
504navigation_timeoutThe page did not reach wait_until in timeout_ms