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: $SYNTHIENT_API_KEY"
Common response codes
A successful stream returns 200 with an NDJSON body, one JSON object per line, held open for up to 30 minutes. 403 means the key lacks the per-stream feed scope. 429 can indicate a team request-rate limit, exhausted key monthly budget, or too many concurrent streams. Retry only when it carries a valid Retry-After. See Errors for the full reference.
Stream proxies
Real-time stream of proxy IP observations.
- Name
ip- Type
- string
- Description
IPv4 or IPv6 address of the proxy.
- Name
provider- Type
- string
- Description
Provider name, such as
orBRIGHTDATA
.IPIDEA
- Name
type- Type
- string
- Description
Proxy type, such as
RESIDENTIAL_PROXY,DATACENTER_PROXY, orMOBILE_PROXY.
- Name
timestamp- Type
- integer
- Description
Unix timestamp in seconds when the proxy was observed.
- Name
country_code- Type
- string
- Description
ISO 3166-1 alpha-2 country of the proxy IP.
- Name
asn- Type
- integer
- Description
Autonomous System Number of the proxy IP.
Request
curl -N https://api.synthient.com/api/v4/feeds/proxies/stream \
-H "x-api-key: $SYNTHIENT_API_KEY"
Sample event
{
"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.
- Name
range_start- Type
- string
- Description
First IP in the anonymizer range.
- Name
range_end- Type
- string
- Description
Last IP in the anonymizer range.
- Name
provider- Type
- string
- Description
Provider name, such as
orNORDVPN
.MULLVAD
- Name
type- Type
- string
- Description
Anonymizer type, such as
COMMERCIAL_VPN,TOR_NODE, orPRIVATE_RELAY.
- Name
timestamp- Type
- integer
- Description
Unix timestamp in milliseconds when the range was observed.
- Name
country_code- Type
- string
- Description
ISO 3166-1 alpha-2 country of
range_start, when available.
- Name
asn- Type
- integer
- Description
Autonomous System Number of
range_start, when available.
Request
curl -N https://api.synthient.com/api/v4/feeds/anonymizers/stream \
-H "x-api-key: $SYNTHIENT_API_KEY"
Sample event
{
"range_start": "2.56.252.0",
"range_end": "2.56.252.255",
"provider": "NORDVPN",
"type": "COMMERCIAL_VPN",
"country_code": "NL",
"asn": 9009,
"timestamp": 1762605697000
}
Stream torrents
Real-time stream of torrent peer sightings from the DHT network and trackers, with info hash, metadata, and observed peers.
- Name
info_hash- Type
- string
- Description
40-character hex SHA-1 info hash of the torrent.
- Name
name- Type
- string
- Description
Torrent name from metadata.
- Name
magnet_uri- Type
- string
- Description
Magnet URI for the torrent.
- Name
total_size- Type
- integer
- Description
Total size of files in bytes.
- Name
piece_length- Type
- integer
- Description
Piece length in bytes.
- Name
file_count- Type
- integer
- Description
Number of files in the torrent.
- Name
files- Type
- array<object>
- Description
Per-file
pathandlengthin bytes.
- Name
peers- Type
- array<object>
- Description
Observed peers:
ip,port,sourceofDHT,PEX, ortracker, andencrypted.
- Name
timestamp- Type
- integer
- Description
Unix timestamp in seconds when the torrent was observed.
Request
curl -N https://api.synthient.com/api/v4/feeds/torrents/stream \
-H "x-api-key: $SYNTHIENT_API_KEY"
Sample event
{
"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 raw NDJSON consumer reads the response body line by line, skips blank heartbeat lines, and parses each remaining line as JSON. The SDKs handle this framing and retry transient connection-establishment failures with bounded backoff and Retry-After handling.
These consumers reconnect immediately after the server's clean close, normally every ~30 minutes. Any error that remains after the SDK's connection retries, or occurs while reading an established stream, is surfaced to the application. There is no resume cursor, so events sent while disconnected are missed. See Rate Limits for the retry policy.
NDJSON Consumer
from synthient import Client
with Client() as client:
while True:
with client.proxies.stream() as events:
for event in events:
print(event.ip, event.provider, event.type)