Firehose

Synthient streams every data feed in real time as newline-delimited JSON (NDJSON) over a long-lived HTTP connection. Each line of the response is one complete JSON event. Connections stay open for up to 30 minutes before the server cleanly closes them — clients should reconnect immediately on disconnect. The server also emits a blank-line heartbeat every 15 seconds so intermediaries don't drop idle connections.

The stream identifiers covered on this page are:

proxies, anonymizers, torrents.

Authentication

All endpoints are served from https://api.synthient.com under /api/v4 and require your API key in the x-api-key header. Each stream requires its own scope (PROXY_FIREHOSE, ANONYMIZERS_STREAM, TORRENTS_STREAM).

curl -N https://api.synthient.com/api/v4/feeds/proxies/stream \
  -H "x-api-key: $API_KEY"

Common response codes

Stream proxies

Real-time stream of proxy IP observations.

curl -N https://api.synthient.com/api/v4/feeds/proxies/stream \
  -H "x-api-key: $API_KEY"

{
  "ip": "38.238.45.9",
  "provider": "DATAIMPULSE",
  "type": "RESIDENTIAL_PROXY",
  "timestamp": 1762605697,
  "country_code": "US",
  "asn": 174
}

Stream anonymizers

Real-time stream of anonymizer observations — VPNs, Tor exits, and relay-class detections. Anonymizer events emit IP ranges rather than individual addresses.

curl -N https://api.synthient.com/api/v4/feeds/anonymizers/stream \
  -H "x-api-key: $API_KEY"

{
  "range_start": "2.56.252.0",
  "range_end": "2.56.252.255",
  "provider": "NORDVPN",
  "type": "COMMERCIAL_VPN",
  "timestamp": 1762605697
}

Stream torrents

Real-time stream of torrent peer sightings from the DHT network and trackers, with info hash, metadata, and observed peers.

curl -N https://api.synthient.com/api/v4/feeds/torrents/stream \
  -H "x-api-key: $API_KEY"

{
  "info_hash": "abcdef0123456789abcdef0123456789abcdef01",
  "name": "ubuntu-26.04-desktop-amd64.iso",
  "magnet_uri": "magnet:?xt=urn:btih:abcdef0123456789abcdef0123456789abcdef01&dn=ubuntu-26.04-desktop-amd64.iso",
  "total_size": 4831838208,
  "piece_length": 2097152,
  "file_count": 1,
  "files": [
    { "path": "ubuntu-26.04-desktop-amd64.iso", "length": 4831838208 }
  ],
  "peers": [
    { "ip": "203.0.113.42", "port": 51413, "source": "DHT", "encrypted": true },
    { "ip": "198.51.100.17", "port": 6881, "source": "PEX", "encrypted": false }
  ],
  "timestamp": 1762605697
}

Consuming streams

A minimal NDJSON consumer reads the response body line by line and parses each line as JSON. The server cleanly closes connections every ~30 minutes — treat that as the normal case and reconnect immediately. On a failed reconnect, use exponential backoff with jitter: start at 1s, double up to a 60s cap, randomize ±25% so concurrent workers don't synchronize. See Rate Limits for the full retry recipe.

import json, os, random, time, requests

URL = "https://api.synthient.com/api/v4/feeds/proxies/stream"
HEADERS = {"x-api-key": os.environ["API_KEY"]}

attempt = 0
while True:
    try:
        with requests.get(URL, headers=HEADERS, stream=True, timeout=None) as r:
            r.raise_for_status()
            attempt = 0  # successful connect — reset backoff
            for line in r.iter_lines(decode_unicode=True):
                if not line:
                    continue
                event = json.loads(line)
                handle(event)
    except requests.RequestException:
        delay = min(60, 2 ** attempt) * random.uniform(0.75, 1.25)
        time.sleep(delay)
        attempt += 1