scrape_api.py

"""
NikaProxy scrape API example.

Instead of routing your client through an HTTP proxy, you POST a URL to our
REST endpoint and we do the proxying server-side. Response comes back as JSON
with the destination's status code, headers, and body.

Use this when:
  - you can't easily plumb a proxy into your runtime (AWS Lambda, edge runtimes,
    browser-side fetches)
  - you want NikaProxy to handle TLS fingerprinting for you (`tlsProfile` /
    `bucket` fields below) without having to install our CA locally
  - one-shot scrapes where setting up the proxy URL is more friction than the
    request itself

Run:
    export NIKA_API_KEY="nka_..."
    python scrape_api.py
"""

import os
import requests

API_KEY = os.environ["NIKA_API_KEY"]

resp = requests.post(
    "https://nikaproxy.com/api/scrape/fetch",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type":  "application/json",
    },
    json={
        # Target — full URL including scheme + path + query
        "url":     "https://httpbin.org/headers",
        "method":  "GET",

        # Optional: pick a country for the residential exit
        "country": "US",

        # Optional: sticky session ID. Same value across requests → same exit IP
        # for the sticky window. Omit for rotating (fresh IP per request).
        # "sessionId": "my-flow-42",
        # "lifetimeMinutes": 30,

        # Optional: TLS Pro/Ultra — pin a browser TLS fingerprint at the engine
        # side. Customer doesn't install our CA; the engine signs the handshake.
        # "tlsProfile":  "chrome_131",
        # "autoEmulate": True,  # also inject matching browser headers (UA, Sec-CH-UA*, Accept-*)

        # Optional: TLS Ultra — instead of pinning a profile, ask for a
        # coordinated exit (L4 TCP fingerprint + L7 TLS profile both match
        # the requested device family).
        # "bucket":  "win11",
        # "kind":    "browser",     # or "library"

        # Custom headers — passed through verbatim (subject to Auto-Emulate
        # rules if autoEmulate=true). Drop the Cookie jar, JSON body, etc. here.
        "headers": {
            "Accept": "application/json",
        },

        # POST body (string). For GET/HEAD leave it out or set to "".
        # "body": "{\"q\":\"hello\"}",

        # Return the response with full headers wrapped in JSON instead of
        # raw passthrough. Useful when you need to read response headers.
        # "envelope": True,
    },
    timeout=60,
)
resp.raise_for_status()

# When envelope=False (default), the response IS the destination's response
# (status + headers + body forwarded transparently). The destination's body
# is here as bytes.
print("HTTP",                      resp.status_code)
print("Profile used   :", resp.headers.get("X-Nika-Profile",    "—"))
print("Upstream ms    :", resp.headers.get("X-Nika-Elapsed-Ms", "—"))
print("Bytes delivered:", resp.headers.get("X-Nika-Bytes-Used", "—"))
print("---")
print(resp.text[:2000])