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