# 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`, `ja4t`. > **Note**: Honeypot captures (`honeypot_http`, `honeypot_https`, `honeypot_dns`, `honeypot_adb`) are documented separately under [Helios](https://docs.synthient.com/enterprise/helios), the Synthient honeypot platform. ## 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`, `JA4T_STREAM`). ```bash title="cURL" curl -N https://api.synthient.com/api/v4/feeds/proxies/stream \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient stream proxies --duration 5s ``` > **Note**: Use `curl -N` (or your client's equivalent unbuffered/streaming mode) so that lines are delivered to your handler as soon as they arrive. A single API key may only hold a small number of concurrent streams per feed; excess connections are rejected with `429`. --- ## 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](https://docs.synthient.com/errors) for the full reference. --- ## Stream proxies (GET /api/v4/feeds/proxies/stream) [Open in the API playground](https://api.synthient.com/playground?endpoint=streamProxies) Real-time stream of proxy IP observations. - `ip` `string` — IPv4 or IPv6 address of the proxy. - `provider` `string` — Provider name, such as `BRIGHTDATA` or `IPIDEA`. - `type` `string` — Proxy type, such as `RESIDENTIAL_PROXY`, `DATACENTER_PROXY`, or `MOBILE_PROXY`. - `timestamp` `integer` — Unix timestamp in **seconds** when the proxy was observed. - `country_code` `string` — ISO 3166-1 alpha-2 country of the proxy IP. - `asn` `integer` — Autonomous System Number of the proxy IP. **Request** `GET /api/v4/feeds/proxies/stream` ```bash title="cURL" curl -N https://api.synthient.com/api/v4/feeds/proxies/stream \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient stream proxies ``` **Sample event** ```json title="Event" { "ip": "38.238.45.9", "provider": "DATAIMPULSE", "type": "RESIDENTIAL_PROXY", "timestamp": 1762605697, "country_code": "US", "asn": 174 } ``` ```json title="Datacenter" { "ip": "45.137.21.88", "provider": "OXYLABS", "type": "DATACENTER_PROXY", "timestamp": 1762605712, "country_code": "DE", "asn": 200651 } ``` ```json title="Mobile" { "ip": "49.207.182.14", "provider": "IPROYAL", "type": "MOBILE_PROXY", "timestamp": 1762605733, "country_code": "IN", "asn": 24560 } ``` > **Note**: Events are delivered as **newline-delimited JSON**: each event arrives as a single line. The samples above are pretty-printed for readability. --- ## Stream anonymizers (GET /api/v4/feeds/anonymizers/stream) [Open in the API playground](https://api.synthient.com/playground?endpoint=streamAnonymizers) Real-time stream of anonymizer observations: VPNs, Tor exits, and relay-class detections. Anonymizer events emit IP **ranges** rather than individual addresses. - `range_start` `string` — First IP in the anonymizer range. - `range_end` `string` — Last IP in the anonymizer range. - `provider` `string` — Provider name, such as `NORDVPN` or `MULLVAD`. - `type` `string` — Anonymizer type, such as `COMMERCIAL_VPN`, `TOR_NODE`, or `PRIVATE_RELAY`. - `timestamp` `integer` — Unix timestamp in **milliseconds** when the range was observed. - `country_code` `string` — ISO 3166-1 alpha-2 country of `range_start`, when available. - `asn` `integer` — Autonomous System Number of `range_start`, when available. **Request** `GET /api/v4/feeds/anonymizers/stream` ```bash title="cURL" curl -N https://api.synthient.com/api/v4/feeds/anonymizers/stream \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient stream anonymizers ``` **Sample event** ```json title="VPN" { "range_start": "2.56.252.0", "range_end": "2.56.252.255", "provider": "NORDVPN", "type": "COMMERCIAL_VPN", "country_code": "NL", "asn": 9009, "timestamp": 1762605697000 } ``` ```json title="Tor" { "range_start": "185.220.101.32", "range_end": "185.220.101.32", "provider": "TOR", "type": "TOR_NODE", "country_code": "DE", "asn": 60729, "timestamp": 1762605714000 } ``` ```json title="Relay" { "range_start": "172.224.224.0", "range_end": "172.224.231.255", "provider": "APPLE", "type": "PRIVATE_RELAY", "country_code": "US", "asn": 36183, "timestamp": 1762605731000 } ``` --- ## Stream torrents (GET /api/v4/feeds/torrents/stream) [Open in the API playground](https://api.synthient.com/playground?endpoint=streamTorrents) Real-time stream of torrent peer sightings from the DHT network and trackers, with info hash, metadata, and observed peers. - `info_hash` `string` — 40-character hex SHA-1 info hash of the torrent. - `name` `string` — Torrent name from metadata. - `magnet_uri` `string` — Magnet URI for the torrent. - `total_size` `integer` — Total size of files in bytes. - `piece_length` `integer` — Piece length in bytes. - `file_count` `integer` — Number of files in the torrent. - `files` `array` — Per-file `path` and `length` in bytes. - `peers` `array` — Observed peers: `ip`, `port`, `source` of `DHT`, `PEX`, or `tracker`, and `encrypted`. - `timestamp` `integer` — Unix timestamp in **seconds** when the torrent was observed. **Request** `GET /api/v4/feeds/torrents/stream` ```bash title="cURL" curl -N https://api.synthient.com/api/v4/feeds/torrents/stream \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` ```bash title="CLI" synthient stream torrents ``` **Sample event** ```json title="Single-file" { "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 } ``` ```json title="Multi-file" { "info_hash": "1f2e3d4c5b6a7988170615243342510fafedcb91", "name": "Big.Buck.Bunny.2008.1080p.BluRay", "magnet_uri": "magnet:?xt=urn:btih:1f2e3d4c5b6a7988170615243342510fafedcb91", "total_size": 8642097152, "piece_length": 4194304, "file_count": 3, "files": [ { "path": "Big.Buck.Bunny.2008.1080p.BluRay.mkv", "length": 8638901248 }, { "path": "subs/eng.srt", "length": 84512 }, { "path": "README.txt", "length": 3111392 } ], "peers": [ { "ip": "45.137.21.88", "port": 6881, "source": "tracker", "encrypted": false }, { "ip": "2a01:4f8:c17:b8f::1", "port": 51413, "source": "DHT", "encrypted": true }, { "ip": "82.165.224.31", "port": 6890, "source": "PEX", "encrypted": true } ], "timestamp": 1762605731 } ``` --- ## Stream JA4T fingerprints (GET /api/v4/feeds/ja4t/stream) Real-time stream of JA4T TCP fingerprints observed from proxy addresses. Requires the `JA4T_STREAM` scope; Parquet exports use `JA4T_FEED`. - `ip` `string` — IPv4 or IPv6 address the fingerprint was observed from. - `ja4t` `string` — JA4T TCP fingerprint. - `provider` `string` — Provider service tag associated with the address. - `type` `string` — Service category, such as `DATACENTER_PROXY`. - `timestamp` `integer` — Unix timestamp in **seconds** when the fingerprint was observed. - `country_code` `string` — ISO 3166-1 alpha-2 country code of the address. - `asn` `integer` — Autonomous System Number of the address. **Request** `GET /api/v4/feeds/ja4t/stream` ```bash title="cURL" curl -N https://api.synthient.com/api/v4/feeds/ja4t/stream \ -H "x-api-key: $SYNTHIENT_API_KEY" ``` **Sample event** ```json title="Event" { "ip": "109.176.45.49", "ja4t": "43080_2-4-8-1-3_1436_9", "provider": "PROXYJET_DATACENTER", "type": "DATACENTER_PROXY", "timestamp": 1779818967, "country_code": "US", "asn": 16276 } ``` --- ## 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](https://docs.synthient.com/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. This also stops a `429` without `Retry-After` from becoming an endless reconnect loop. There is no resume cursor, so events sent while disconnected are missed. See [Rate Limits](https://docs.synthient.com/rate-limits#retry-guidance) for the retry policy. **NDJSON Consumer** ```python title="Python" 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) ``` ```go title="Go" package main import ( "context" "fmt" "log" "os" "github.com/synthient/synthient-go" ) func main() { client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY")) if err != nil { log.Fatal(err) } err = consumeProxies(context.Background(), client) if err != nil { log.Fatal(err) } } func consumeProxies(ctx context.Context, client *synthient.Client) error { for { for event, err := range client.Proxies.Stream(ctx) { if err != nil { return err } fmt.Println(event.IP, event.Provider, event.Type) } } } ```