Types

The fields of every response and event type, and the enumerations they use.

Lookup types

Every response type is an immutable pydantic model. Fields the API adds later are ignored, and a response with a known field of the wrong type raises SynthientError. Unix timestamps are decoded to timezone-aware datetime values in UTC, as described under Event types.

IPInfo

The intelligence Synthient holds for an IP address. See the IP API for how each field is derived.

Name
ip
Type
IPv4Address | IPv6Address
Description
The address that was looked up.
Name
network
Type
Network | None
Description
The network that announces the address, or None if the API has no network data.
Name
location
Type
Location | None
Description
The geolocation of the address, or None if the API has no location data.
Name
intelligence
Type
Intelligence | None
Description
The risk score and the proxy, VPN, and device observations for the address, or None if the API has no intelligence data.

Network

The network that announces an address.

Name
asn
Type
int
Description
The autonomous system number, or 0 if the address is not routed.
Name
isp
Type
str
Description
The internet service provider that operates the network.
Name
type
Type
str
Description
The kind of network, such as "RESIDENTIAL", "MOBILE", or "DATACENTER". See Enumerations.
Name
org
Type
str | None
Description
The organization the address is registered to, or None if unknown.
Name
domain
Type
str | None
Description
The network operator's domain, or None if unknown.
Name
abuse_email
Type
str | None
Description
The operator's abuse contact email, or None if unknown.
Name
abuse_phone
Type
str | None
Description
The operator's abuse contact phone number, or None if unknown.

Location

The geolocation of an address.

Name
country
Type
str
Description
The ISO 3166-1 alpha-2 country code.
Name
state
Type
str
Description
The state or region.
Name
city
Type
str
Description
The city.
Name
timezone
Type
str
Description
The IANA time zone name.
Name
latitude
Type
float
Description
The latitude in degrees.
Name
longitude
Type
float
Description
The longitude in degrees.
Name
geo_hash
Type
str
Description
The geohash of the coordinates.

Intelligence

Synthient's assessment of an address. See Methodology for how it is built.

Name
risk_score
Type
int
Description
The risk of the address, from 0 to 100.
Name
categories
Type
list[str]
Description
The kinds of services seen on the address, such as "RESIDENTIAL_PROXY". New values may be added.
Name
behavior
Type
list[str]
Description
Behaviors observed from the address. New values may be added.
Name
providers
Type
list[Provider]
Description
The proxy, VPN, and anonymizer services seen using the address. An empty list does not mean the address is clean.
Name
devices
Type
list[Device]
Description
The device types seen behind the address.

Provider

A proxy, VPN, or anonymizer service seen using an address.

Name
name
Type
str
Description
The service tag, such as "BRIGHTDATA". The API names this field provider. See Service Tags.
Name
type
Type
str
Description
The service category.
Name
last_seen
Type
datetime
Description
When the service was last seen on the address.

Device

A device type seen behind an address.

Name
os
Type
str
Description
The operating system, such as "Android", "iOS", or "Windows". See Enumerations.
Name
version
Type
str
Description
The operating system version.
Name
last_seen
Type
datetime
Description
When the device was last seen.

Domain types

DomainInfo

The honeypot traffic Synthient has observed for a domain.

Name
domain
Type
str
Description
The domain that was looked up.
Name
status
Type
str
Description
"active" when the domain had events in the last 24 hours, otherwise "inactive". See Enumerations.
Name
stats
Type
DomainStats
Description
Aggregate event counts.
Name
unique_ips
Type
UniqueIPs
Description
Counts of the distinct source addresses.
Name
time_series
Type
list[TimeSeriesPoint]
Description
Daily event counts.
Name
top_asn
Type
ASNCount | None
Description
The network that sent the most events, or None when there are no events.
Name
top_subdomains
Type
list[SubdomainCount]
Description
The most targeted subdomains.
Name
top_ports
Type
list[PortCount]
Description
The most targeted ports.
Name
geo_distribution
Type
list[CountryCount]
Description
Event counts by source country.
Name
hour_dow_heatmap
Type
list[list[int]]
Description
Event counts over the last 30 days as 7 rows by 24 columns, all in UTC, indexed as hour_dow_heatmap[day][hour]. Rows are days of the week from Monday (0) to Sunday (6), the same numbering as datetime.weekday().
Name
activity_stats
Type
ActivityStats
Description
The hourly activity pattern.
Name
recent_events
Type
list[DomainEvent]
Description
The most recent events, capped by the limit passed to lookup_domain.

DomainStats

Aggregate event counts for a domain.

Name
events_24h
Type
int
Description
Events in the last 24 hours.
Name
total_events_30d
Type
int
Description
Events in the last 30 days.

UniqueIPs

The distinct source addresses seen for a domain.

Name
value_24h
Type
int
Description
Distinct source addresses in the last 24 hours.
Name
value_30d
Type
int
Description
Distinct source addresses in the last 30 days.
Name
sparkline_24h
Type
list[int]
Description
Hourly counts for the last 24 hours.

TimeSeriesPoint

The event counts for one day.

Name
date
Type
datetime
Description
The start of the day.
Name
events
Type
int
Description
Events that day.
Name
unique_ips
Type
int
Description
The number of distinct source addresses that day.

ASNCount

An autonomous system and its event count.

Name
asn
Type
int
Description
The autonomous system number.
Name
events
Type
int
Description
Events from that network.

SubdomainCount

A subdomain and its event count.

Name
subdomain
Type
str
Description
The subdomain.
Name
count
Type
int
Description
The number of events that targeted it.

PortCount

A port and its event count.

Name
port
Type
int
Description
The port.
Name
count
Type
int
Description
The number of events that targeted it.

CountryCount

A source country and its counts.

Name
country_code
Type
str
Description
The ISO 3166-1 alpha-2 country code.
Name
events
Type
int
Description
Events from that country.
Name
unique_ips
Type
int
Description
Distinct source addresses from that country.

ActivityStats

The hourly activity pattern of a domain.

Name
cadence
Type
str
Description
A sentence describing how events are spread over time, such as "Activity is burst-driven with significant peaks.". See Enumerations.
Name
median_per_hour
Type
int
Description
The median number of events per hour.
Name
p95_per_hour
Type
int
Description
The 95th percentile of events per hour.
Name
peak_hour
Type
int
Description
The busiest UTC hour of the day over the last 30 days.
Name
quiet_hour
Type
int
Description
The quietest UTC hour of the day over the last 30 days.

DomainEvent

A single honeypot event for a domain.

Name
timestamp
Type
datetime
Description
When the event happened.
Name
source_ip_masked
Type
str
Description
The full proxy exit address that carried the event. Despite the name, the address is not masked.
Name
target_subdomain
Type
str
Description
The subdomain that was targeted.
Name
country_code
Type
str
Description
The source country.
Name
port
Type
int
Description
The destination port.

Account types

Account

The account that owns an API key.

Name
email
Type
str
Description
The account's email address.
Name
first_name
Type
str
Description
The account holder's first name.
Name
last_name
Type
str
Description
The account holder's last name.
Name
organization
Type
Organization
Description
The organization the account belongs to.
Name
scopes
Type
list[str]
Description
The permissions granted to the key, such as "BASIC" or "PROXY_FEEDS". See Enumerations.
Name
lookup_quota
Type
LookupQuota
Description
The remaining lookup credits.
Name
api_key
Type
AccountAPIKey | None
Description
The API key used for the request, or None if the API did not include it.

Organization

The organization an account belongs to.

Name
id
Type
str
Description
The organization's ID.
Name
name
Type
str
Description
The organization's name.
Name
relation
Type
str
Description
The account's role, such as "OWNER", "ADMIN", or "MEMBER". See Enumerations.

LookupQuota

The lookup credits available to an account.

Name
credits
Type
int
Description
The number of lookup credits remaining.
Name
resets_in
Type
int
Description
The number of seconds until the credits reset.

AccountAPIKey

The API key a request was made with.

Name
id
Type
str
Description
Identifies the key. It is not the secret key itself.
Name
name
Type
str
Description
The key's display name.
Name
created_at
Type
datetime
Description
When the key was created, parsed from the RFC 3339 string the API sends.

Export types

ExportPage

One page of a feed's exports, newest first.

Name
stream
Type
str
Description
The feed's stream identifier, such as "proxies".
Name
exports
Type
list[Export]
Description
The exports on this page. The API names this field feeds.
Name
next_cursor
Type
str | None
Description
Fetches the next page through the cursor argument of list_exports. It is None or "" on the last page.

Export

A Parquet export of a feed.

Name
id
Type
str
Description
Identifies the export as "YYYY-MM-DD", "YYYY-MM-DD/H", or "latest", for export_meta, download, and download_url. On the first page of a listing, the newest hourly export has the ID "latest", a moving alias for the freshest export. To keep a stable ID, build it from date and hour, such as "2026-10-14/21".
Name
kind
Type
str
Description
Either "hourly" or "daily".
Name
date
Type
date
Description
The UTC day of the export.
Name
hour
Type
int | None
Description
The UTC hour of an hourly export, or None for a daily export.
Name
size_bytes
Type
int
Description
The size of the Parquet file in bytes.
Name
row_count
Type
int
Description
The number of rows in the file.
Name
checksum
Type
str
Description
The hex-encoded SHA-256 of the Parquet file.
Name
created_at
Type
datetime
Description
When the export was created.
Name
download_path
Type
str
Description
The API path of the export's download, including the version prefix.

ExportMeta

A Parquet export's metadata, without its contents.

Name
id
Type
str
Description
The export ID.
Name
stream
Type
str
Description
The feed's stream identifier.
Name
kind
Type
str
Description
Either "hourly" or "daily".
Name
format
Type
str
Description
The file format, "parquet".
Name
date
Type
datetime
Description
The start of the export's UTC day or hour.
Name
hour
Type
int | None
Description
The UTC hour of an hourly export, or None for a daily export.
Name
rows
Type
int
Description
The number of rows in the file.
Name
size
Type
int
Description
The size of the Parquet file in bytes.
Name
checksum
Type
str
Description
The hex-encoded SHA-256 of the Parquet file.
Name
created_at
Type
datetime
Description
When the export was created.
Name
parquet_schema
Type
ParquetSchema
Description
The Parquet columns. The API names this field schema.

ParquetSchema

The columns of a Parquet export.

Name
fields
Type
list[ParquetColumn]
Description
The columns in file order.

ParquetColumn

A column of a Parquet export.

Name
name
Type
str
Description
The column name.
Name
type
Type
str
Description
The column type, such as "string" or "int64". See Enumerations.

Event types

Stream payloads follow the Firehose and Helios documentation, with one exception: HTTPS events also send signature_algorithms_cert, which TLSClientHello does not model, so the SDK drops it. Fields the API omits are None. Every field of the proxy, anonymizer, torrent, and JA4T events is optional, while the Helios events require the fields typed without None.

Timestamps are decoded to timezone-aware datetime values in UTC.

Units: The API sends Unix seconds, except on anonymizer and Helios HTTP, HTTPS, and DNS events, where it sends milliseconds. Values of 1e12 or more are read as milliseconds.

ProxyEvent

A proxy sighting from the proxies feed.

Name
ip
Type
str | None
Description
The proxy exit address.
Name
provider
Type
str | None
Description
The proxy service tag.
Name
type
Type
str | None
Description
The service category, such as "RESIDENTIAL_PROXY". See Enumerations.
Name
country_code
Type
str | None
Description
The ISO 3166-1 alpha-2 country of the address.
Name
asn
Type
int | None
Description
The autonomous system number of the address.
Name
timestamp
Type
datetime | None
Description
When the proxy was seen.

AnonymizerEvent

A VPN or anonymizer IP range from the anonymizers feed.

Name
range_start
Type
str | None
Description
The first address of the range.
Name
range_end
Type
str | None
Description
The last address of the range.
Name
provider
Type
str | None
Description
The service tag.
Name
type
Type
str | None
Description
The service category, such as "COMMERCIAL_VPN".
Name
country_code
Type
str | None
Description
The ISO 3166-1 alpha-2 country of range_start.
Name
asn
Type
int | None
Description
The autonomous system number of range_start.
Name
timestamp
Type
datetime | None
Description
When the range was seen.

TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker.

Name
info_hash
Type
str | None
Description
The hex-encoded SHA-1 info hash.
Name
name
Type
str | None
Description
The torrent's name.
Name
magnet_uri
Type
str | None
Description
The torrent's magnet link.
Name
total_size
Type
int | None
Description
The total size of the torrent's files in bytes.
Name
piece_length
Type
int | None
Description
The piece size in bytes.
Name
file_count
Type
int | None
Description
The number of files in the torrent.
Name
files
Type
list[TorrentFile] | None
Description
The files in the torrent.
Name
peers
Type
list[TorrentPeer] | None
Description
The peers seen sharing the torrent.
Name
timestamp
Type
datetime | None
Description
When the torrent was seen.

TorrentFile

A file in a torrent.

Name
path
Type
str | None
Description
The file path within the torrent.
Name
length
Type
int | None
Description
The file size in bytes.

TorrentPeer

A peer seen sharing a torrent.

Name
ip
Type
str | None
Description
The peer's address.
Name
port
Type
int | None
Description
The peer's port.
Name
source
Type
str | None
Description
Where the peer was found, such as "DHT", "PEX", or "tracker".
Name
encrypted
Type
bool | None
Description
Whether the peer supports encrypted connections.

JA4TEvent

A JA4T TCP fingerprint sighting.

Name
ip
Type
str | None
Description
The address the fingerprint was seen from.
Name
ja4t
Type
str | None
Description
The JA4T fingerprint.
Name
provider
Type
str | None
Description
The service tag of the address.
Name
type
Type
str | None
Description
The service category, such as "DATACENTER_PROXY".
Name
country_code
Type
str | None
Description
The ISO 3166-1 alpha-2 country of the address.
Name
asn
Type
int | None
Description
The autonomous system number of the address.
Name
timestamp
Type
datetime | None
Description
When the fingerprint was seen.

HeliosMeta

The Helios honeypot sensor that captured an event.

Name
proxy_ip
Type
str | None
Description
The proxy exit address the traffic arrived through.
Name
server
Type
str | None
Description
The sensor that captured the traffic.
Name
pool_id
Type
str | None
Description
The sensor pool.
Name
provider
Type
str | None
Description
The proxy service the traffic arrived through.

HeliosHTTPEvent

An HTTP request captured by a Helios honeypot.

Name
timestamp
Type
datetime
Description
When the request was captured.
Name
tunnel_id
Type
int
Description
Identifies the proxy tunnel the request arrived through.
Name
domain
Type
str
Description
The destination host the tunnel was opened to.
Name
port
Type
int
Description
The destination port.
Name
protocol
Type
str
Description
Always "http".
Name
meta
Type
HeliosMeta
Description
The capturing sensor.
Name
details
Type
HTTPRequestDetails | None
Description
The parsed request.
Name
raw
Type
str | None
Description
The raw request, still base64-encoded as the API sends it. Decode it with base64.b64decode.

HTTPRequestDetails

A parsed HTTP request.

Name
method
Type
str | None
Description
The request method.
Name
uri
Type
str | None
Description
The request target.
Name
version
Type
str | None
Description
The HTTP version, such as "HTTP/1.1".
Name
headers
Type
dict[str, str] | None
Description
The request headers.

HeliosHTTPSEvent

A TLS ClientHello captured by a Helios honeypot.

Name
timestamp
Type
datetime
Description
When the handshake was captured.
Name
tunnel_id
Type
int
Description
Identifies the proxy tunnel the handshake arrived through.
Name
domain
Type
str
Description
The destination host the tunnel was opened to.
Name
port
Type
int
Description
The destination port.
Name
protocol
Type
str
Description
Always "https".
Name
meta
Type
HeliosMeta
Description
The capturing sensor.
Name
details
Type
TLSClientHello | None
Description
The parsed ClientHello, or None when the sensor could not parse the handshake.
Name
raw
Type
str | None
Description
Always None, because the HTTPS sensors do not capture handshake bytes.

TLSClientHello

A TLS ClientHello parsed by a Helios sensor. Fields the sensor could not parse are None, and new fields may be added.

Name
record_version
Type
str | None
Description
The record layer version, such as "TLS 1.0".
Name
handshake_version
Type
str | None
Description
The handshake version, such as "TLS 1.2".
Name
client_random
Type
str | None
Description
The hex-encoded 32-byte client random.
Name
session_id
Type
str | None
Description
The hex-encoded session ID.
Name
session_id_length
Type
int | None
Description
The session ID length in bytes.
Name
sni
Type
str | None
Description
The server_name extension value.
Name
alpn
Type
list[str] | None
Description
The offered application protocols, such as "h2".
Name
cipher_suites
Type
list[TLSCodeName] | None
Description
The offered cipher suites.
Name
compression_methods
Type
list[int] | None
Description
The offered compression methods.
Name
extensions
Type
list[TLSExtension] | None
Description
The extensions in wire order.
Name
supported_versions
Type
list[str] | None
Description
The offered TLS versions.
Name
supported_groups
Type
list[TLSCodeName] | None
Description
The supported key exchange groups.
Name
signature_algorithms
Type
list[TLSCodeName] | None
Description
The offered signature algorithms.
Name
ec_point_formats
Type
list[str] | None
Description
The offered elliptic curve point formats.
Name
key_share_groups
Type
list[str] | None
Description
The groups the client sent key shares for.
Name
psk_key_exchange_modes
Type
list[str] | None
Description
The supported pre-shared key exchange modes.
Name
compress_certificate
Type
list[str] | None
Description
The supported certificate compression algorithms.
Name
has_grease
Type
bool | None
Description
Whether the ClientHello contains GREASE values.
Name
application_settings
Type
bool | None
Description
Whether the client offered application settings (ALPS).
Name
delegated_credentials
Type
bool | None
Description
Whether the client offered the delegated_credentials extension.
Name
encrypt_then_mac
Type
bool | None
Description
Whether the client offered the encrypt_then_mac extension.
Name
extended_master_secret
Type
bool | None
Description
Whether the client offered the extended_master_secret extension.
Name
post_handshake_auth
Type
bool | None
Description
Whether the client offered the post_handshake_auth extension.
Name
renegotiation_info
Type
bool | None
Description
Whether the client offered the renegotiation_info extension.
Name
signed_certificate_timestamps
Type
bool | None
Description
Whether the client offered the signed_certificate_timestamp extension.
Name
status_request
Type
bool | None
Description
Whether the client requested OCSP stapling.

TLSCodeName

A TLS registry code point and its name.

Name
code
Type
int | None
Description
The code point.
Name
name
Type
str | None
Description
The registered name. GREASE values read as "GREASE(0x....)".

TLSExtension

A TLS extension in a ClientHello.

Name
code
Type
int | None
Description
The extension type.
Name
name
Type
str | None
Description
The extension's registered name.
Name
length
Type
int | None
Description
The length of the extension body in bytes.

HeliosDNSEvent

A tunnel destination captured by the Helios DNS honeypot. Despite the feed's name, domain is where the tunnel was opened to, not a DNS query name: names resolved inside a tunneled DNS session are not visible.

Name
timestamp
Type
datetime
Description
When the event was captured.
Name
tunnel_id
Type
int
Description
Identifies the proxy tunnel.
Name
domain
Type
str
Description
The destination host, or an address literal, the tunnel was opened to.
Name
port
Type
int
Description
The destination port.
Name
protocol
Type
str
Description
Always "dns".
Name
meta
Type
HeliosMeta
Description
The capturing sensor.

HeliosADBEvent

An Android Debug Bridge shell command captured by a Helios honeypot. It has no timestamp because the sensors send none.

Name
session
Type
str
Description
Identifies the ADB session as 32 hex characters.
Name
sequential_id
Type
int
Description
The 1-based position of the command within its session.
Name
command
Type
str
Description
The shell command as plain text. Invalid UTF-8 bytes are replaced with U+FFFD.
Name
hash
Type
str
Description
The hex-encoded SHA-256 the sensor assigns to the session's payload. It is not a hash of command: every command in a session shares it, and sessions that replay the same script share it too.

Enumerations

The SDK types every one of these fields as a plain str. It has no enum classes or constants, so compare against the string values below. The API may add values to the sets marked open, so handle unknown values instead of assuming the list is complete.

Network type

The kind of network that announces an address, in Network.type. Open.

Value
`MOBILE`
`SATELLITE`
`IN_FLIGHT_WIFI`
`RESIDENTIAL`
`CORPORATE`
`ACADEMIC`
`DATACENTER`
`GOVERNMENT`

Proxy type

The kind of service seen on an address, in ProxyEvent.type, AnonymizerEvent.type, and JA4TEvent.type. Open.

Value
`FREE_VPN`
`COMMERCIAL_VPN`
`ENTERPRISE_VPN`
`MOBILE_PROXY`
`BLOCKCHAIN_PROXY`
`RESIDENTIAL_PROXY`
`PUBLIC_PROXY`
`DATACENTER_PROXY`
`TOR_NODE`
`PRIVATE_RELAY`
`BOTNET`
`SEARCH_ENGINE`
`AI_CRAWLER`
`SOCIAL_MEDIA`
`UPTIME_MONITOR`
`LINK_PREVIEW`
`SEO_CRAWLER`
`WEB_ARCHIVER`
`WEBHOOK_PROVIDER`
`PAYMENT_PROCESSOR`
`INTERNET_SCANNER`

Operating system

A device operating system, in Device.os. Open.

Value
`Android`
`Chrome OS`
`FreeBSD`
`iOS`
`Linux`
`Mac OS X`
`Windows`

Scope

A permission granted to an API key, in Account.scopes. Open. BASIC authorizes lookups and account. Each feed has one scope for its exports and one for its stream, as listed under Feeds. See Authentication for how scopes are granted.

Value
`BASIC`
`PROXY_FEEDS`
`PROXY_FIREHOSE`
`ANONYMIZERS_FEED`
`ANONYMIZERS_STREAM`
`JA3_FEED`
`JA3_STREAM`
`TORRENTS_FEED`
`TORRENTS_STREAM`
`HONEYPOT_HTTP_FEED`
`HONEYPOT_HTTP_STREAM`
`HONEYPOT_HTTPS_FEED`
`HONEYPOT_HTTPS_STREAM`
`HONEYPOT_ADB_FEED`
`HONEYPOT_ADB_STREAM`
`HONEYPOT_DNS_FEED`
`HONEYPOT_DNS_STREAM`
`JA4_FEED`
`JA4_STREAM`
`JA4T_FEED`
`JA4T_STREAM`
`ADMIN_PROXIES`

Relation

An account's role in its organization, in Organization.relation.

Value
`OWNER`
`ADMIN`
`MEMBER`

Domain status

Whether a domain has recent activity, in DomainInfo.status.

Value	Meaning
`active`	The domain had events in the last 24 hours.
`inactive`	The domain had no events in the last 24 hours, or has never been observed.

Cadence

A sentence describing a domain's activity pattern, in ActivityStats.cadence.

Value
`No activity in the last 30 days.`
`Activity is evenly distributed across the day.`
`Activity follows a weekday business-hours pattern.`
`Activity follows a weekend pattern.`
`Activity is burst-driven with significant peaks.`

Export kind

Whether an export covers an hour or a day, in Export.kind and ExportMeta.kind.

Value
`hourly`
`daily`

Parquet type

The type of a Parquet column, in ParquetColumn.type. Open.

Value
`string`
`int64`
`uint32`
`uint64`
`bool`
`bytes`