Types

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

Lookup types

Response types are interfaces over the API's JSON, so their fields use the API's snake_case names, such as risk_score. The client returns the parsed JSON without validating each field against these types. The one conversion is that Helios tunnel_id values are kept as strings.

IPInfo

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

Name
ip
Type
string
Description
The address that was looked up.
Name
network?
Type
Network
Description
The network that announces the address. Absent when the API has no network data.
Name
location?
Type
Location
Description
The geolocation of the address. Absent when the API has no location data.
Name
intelligence?
Type
Intelligence
Description
The risk score and the proxy, VPN, and device observations for the address. Absent when the API has no intelligence data.

Network

The network that announces an address.

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

Location

The geolocation of an address.

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

Intelligence

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

Name
risk_score
Type
number
Description
The risk of the address, from 0 to 100.
Name
categories
Type
string[]
Description
The kinds of services seen on the address, such as "RESIDENTIAL_PROXY". New values may be added.
Name
behavior
Type
string[]
Description
Behaviors observed from the address. New values may be added.
Name
providers
Type
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
Device[]
Description
The device types seen behind the address.

Provider

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

Name
provider
Type
string
Description
The service tag, such as "BRIGHTDATA". See Service Tags.
Name
type
Type
string
Description
The service category.
Name
last_seen
Type
UnixTime
Description
When the service was last seen using the address.

Device

A device type seen behind an address.

Name
os
Type
DeviceOS
Description
The operating system. See Enumerations.
Name
version
Type
string
Description
The operating system version.
Name
last_seen
Type
UnixTime
Description
When the device was last seen.

Domain types

DomainInfo

The honeypot traffic Synthient has observed for a domain.

Name
domain
Type
string
Description
The domain that was looked up.
Name
status
Type
"active" | "inactive"
Description
"active" when the domain had events in the last 24 hours. A domain that was never observed is "inactive" with zeroed stats.
Name
stats
Type
DomainStats
Description
Aggregate event counts.
Name
unique_ips
Type
UniqueIPs
Description
Counts of the distinct source addresses.
Name
time_series
Type
TimeSeriesPoint[]
Description
Daily event counts.
Name
top_asn?
Type
ASNCount
Description
The network that sent the most events. Absent when there are no events.
Name
top_subdomains
Type
SubdomainCount[]
Description
The most targeted subdomains.
Name
top_ports
Type
PortCount[]
Description
The most targeted ports.
Name
geo_distribution
Type
CountryCount[]
Description
Event counts by source country.
Name
hour_dow_heatmap
Type
number[][]
Description
Event counts over the last 30 days as 7 rows, Monday first, of 24 hourly columns, all in UTC. Index it as hour_dow_heatmap[day][hour]. Day 0 is Monday, unlike Date.prototype.getUTCDay, where 0 is Sunday.
Name
activity_stats
Type
ActivityStats
Description
The hourly activity pattern.
Name
recent_events
Type
DomainEvent[]
Description
The most recent events, capped by LookupDomainOptions.limit.

DomainStats

Aggregate event counts for a domain.

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

UniqueIPs

The distinct source addresses seen for a domain.

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

TimeSeriesPoint

The event counts for one day.

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

ASNCount

An autonomous system and its event count.

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

SubdomainCount

A subdomain and its event count.

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

PortCount

A port and its event count.

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

CountryCount

A source country and its counts.

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

ActivityStats

The hourly activity pattern of a domain.

Name
cadence
Type
ActivityCadence
Description
How events are distributed over time. See Enumerations.
Name
median_per_hour
Type
number
Description
The median number of events per hour.
Name
p95_per_hour
Type
number
Description
The 95th percentile of events per hour.
Name
peak_hour
Type
number
Description
The busiest UTC hour of the day.
Name
quiet_hour
Type
number
Description
The quietest UTC hour of the day.

DomainEvent

A single honeypot event for a domain.

Name
timestamp
Type
UnixTime
Description
When the event happened.
Name
source_ip_masked
Type
string
Description
The full proxy exit address that carried the event. Despite the name, it is not masked.
Name
target_subdomain
Type
string
Description
The subdomain that was targeted.
Name
country_code
Type
string
Description
The source country.
Name
port
Type
number
Description
The targeted port.

Account types

Account

The account that owns an API key.

Name
email
Type
string
Description
The account's email address.
Name
first_name
Type
string
Description
The account holder's first name.
Name
last_name
Type
string
Description
The account holder's last name.
Name
organization
Type
Organization
Description
The organization the account belongs to.
Name
scopes
Type
Scope[]
Description
The permissions granted to the key. See Enumerations.
Name
lookup_quota
Type
LookupQuota
Description
The remaining lookup credits.
Name
api_key?
Type
AccountAPIKey
Description
The API key used for the request.

Organization

The organization an account belongs to.

Name
id
Type
string
Description
The organization's ID.
Name
name
Type
string
Description
The organization's name.
Name
relation
Type
"OWNER" | "ADMIN" | "MEMBER"
Description
The account's role in the organization.

LookupQuota

The lookup credits available to an account.

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

AccountAPIKey

The API key a request was made with.

Name
id
Type
string
Description
The key ID. It is not the secret key.
Name
name
Type
string
Description
The key's display name.
Name
created_at
Type
string
Description
When the key was created, as an RFC 3339 string.

Export types

ExportPage

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

Name
stream
Type
string
Description
The feed's stream identifier, such as "proxies".
Name
feeds
Type
Export[]
Description
The exports on this page.
Name
next_cursor?
Type
string | null
Description
Fetches the next page through ListExportsOptions.cursor. It is absent, null, or "" on the last page.

Export

A Parquet export of a feed.

Name
id
Type
string
Description
Identifies the export: "YYYY-MM-DD" for a daily export, "YYYY-MM-DD/H" with an unpadded hour for an hourly one, or "latest" for the newest hourly export on the first page. Pass it to exportMeta, downloadURL, or download.
Name
kind
Type
"hourly" | "daily"
Description
Whether the export covers a UTC day or a UTC hour.
Name
date
Type
string
Description
The UTC day of the export as "YYYY-MM-DD".
Name
hour?
Type
number | null
Description
The UTC hour of an hourly export. Absent or null for a daily export.
Name
size_bytes
Type
number
Description
The size of the Parquet file in bytes.
Name
row_count
Type
number
Description
The number of rows in the file.
Name
checksum
Type
string
Description
The hex-encoded SHA-256 of the Parquet file.
Name
created_at
Type
UnixTime
Description
When the export was created.
Name
download_path
Type
string
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
string
Description
The export ID.
Name
stream
Type
string
Description
The feed's stream identifier.
Name
kind
Type
"hourly" | "daily"
Description
Whether the export covers a UTC day or a UTC hour.
Name
format
Type
"parquet"
Description
The file format, always "parquet".
Name
date
Type
UnixTime
Description
The start of the export: midnight UTC for a daily export, the hour for an hourly one. Unlike Export.date, it is a number.
Name
hour?
Type
number | null
Description
The UTC hour of an hourly export. Absent or null for a daily export.
Name
rows
Type
number
Description
The number of rows in the file.
Name
size
Type
number
Description
The size of the Parquet file in bytes.
Name
checksum
Type
string
Description
The hex-encoded SHA-256 of the Parquet file.
Name
created_at
Type
UnixTime
Description
When the export was created.
Name
schema
Type
ParquetSchema
Description
The Parquet columns.

ParquetSchema

The columns of a Parquet export.

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

ParquetColumn

A column of a Parquet export.

Name
name
Type
string
Description
The column name.
Name
type
Type
ParquetType
Description
The column type. See Enumerations.

Event types

Event fields keep the stream's JSON names. See Firehose and Helios for the payloads. Fields the API omits are absent.

ProxyEvent

A proxy sighting from the proxies feed.

Name
ip?
Type
string
Description
The proxy exit address.
Name
provider?
Type
string
Description
The proxy service tag.
Name
type?
Type
ServiceCategory
Description
The service category. See Enumerations.
Name
country_code?
Type
string
Description
The ISO 3166-1 alpha-2 country of the address.
Name
asn?
Type
number
Description
The autonomous system number of the address.
Name
timestamp?
Type
UnixTime
Description
When the proxy was seen, in Unix seconds.

AnonymizerEvent

A VPN or anonymizer IP range from the anonymizers feed.

Name
range_start?
Type
string
Description
The first address of the range.
Name
range_end?
Type
string
Description
The last address of the range.
Name
provider?
Type
string
Description
The service tag.
Name
type?
Type
ServiceCategory
Description
The service category, such as "COMMERCIAL_VPN".
Name
country_code?
Type
string
Description
The ISO 3166-1 alpha-2 country of range_start.
Name
asn?
Type
number
Description
The autonomous system number of range_start.
Name
timestamp?
Type
UnixTime
Description
When the range was seen, in Unix milliseconds.

TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker.

Name
info_hash?
Type
string
Description
The hex-encoded SHA-1 info hash.
Name
name?
Type
string
Description
The torrent's name.
Name
magnet_uri?
Type
string
Description
The torrent's magnet link.
Name
total_size?
Type
number
Description
The total size of the torrent's files in bytes.
Name
piece_length?
Type
number
Description
The piece size in bytes.
Name
file_count?
Type
number
Description
The number of files in the torrent.
Name
files?
Type
TorrentFile[]
Description
The files in the torrent.
Name
peers?
Type
TorrentPeer[]
Description
The peers seen sharing the torrent.
Name
timestamp?
Type
UnixTime
Description
When the torrent was seen, in Unix seconds.

TorrentFile

A file in a torrent.

Name
path?
Type
string
Description
The file path within the torrent.
Name
length?
Type
number
Description
The file size in bytes.

TorrentPeer

A peer seen sharing a torrent.

Name
ip?
Type
string
Description
The peer's address.
Name
port?
Type
number
Description
The peer's port.
Name
source?
Type
string
Description
Where the peer was found, such as "DHT", "PEX", or "tracker".
Name
encrypted?
Type
boolean
Description
Whether the peer supports encrypted connections.

JA4TEvent

A JA4T TCP fingerprint sighting.

Name
ip?
Type
string
Description
The address the fingerprint was seen from.
Name
ja4t?
Type
string
Description
The JA4T fingerprint.
Name
provider?
Type
string
Description
The service tag of the address.
Name
type?
Type
ServiceCategory
Description
The service category, such as "DATACENTER_PROXY".
Name
country_code?
Type
string
Description
The ISO 3166-1 alpha-2 country of the address.
Name
asn?
Type
number
Description
The autonomous system number of the address.
Name
timestamp?
Type
UnixTime
Description
When the fingerprint was seen, in Unix seconds.

HeliosMeta

The Helios honeypot sensor that captured an event.

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

HeliosHTTPEvent

An HTTP request captured by a Helios honeypot.

Name
timestamp
Type
UnixTime
Description
When the request was captured, in Unix milliseconds.
Name
tunnel_id
Type
string
Description
Identifies the proxy tunnel the request arrived through. It is an unsigned 64-bit integer on the wire, kept as its exact decimal digits because a number loses precision above Number.MAX_SAFE_INTEGER.
Name
domain
Type
string
Description
The destination host the tunnel was opened to.
Name
port
Type
number
Description
The destination port.
Name
protocol
Type
"http"
Description
Always "http".
Name
meta
Type
HeliosMeta
Description
The capturing sensor.
Name
details?
Type
HTTPRequestDetails
Description
The parsed request.
Name
raw?
Type
string
Description
The raw request bytes, base64-encoded as the API sends them.

HTTPRequestDetails

A parsed HTTP request.

Name
method?
Type
string
Description
The request method.
Name
uri?
Type
string
Description
The request target.
Name
version?
Type
string
Description
The HTTP version, such as "HTTP/1.1".
Name
headers?
Type
Record<string, string>
Description
The request headers.

HeliosHTTPSEvent

A TLS ClientHello captured by a Helios honeypot.

Name
timestamp
Type
UnixTime
Description
When the handshake was captured, in Unix milliseconds.
Name
tunnel_id
Type
string
Description
Identifies the proxy tunnel the handshake arrived through. It is an unsigned 64-bit integer on the wire, kept as its exact decimal digits because a number loses precision above Number.MAX_SAFE_INTEGER.
Name
domain
Type
string
Description
The destination host the tunnel was opened to.
Name
port
Type
number
Description
The destination port.
Name
protocol
Type
"https"
Description
Always "https".
Name
meta
Type
HeliosMeta
Description
The capturing sensor.
Name
details?
Type
TLSClientHello | null
Description
The parsed ClientHello, or null when the sensor could not parse the handshake.
Name
raw?
Type
string | null
Description
Always null, because the HTTPS sensors do not capture handshake bytes.

TLSClientHello

A TLS ClientHello as parsed by the Helios sensors. Fields the sensor could not parse are absent, and new fields may appear.

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

TLSCodeName

A TLS registry value, such as a cipher suite or group, with its name. GREASE values are named "GREASE(0x....)".

Name
code?
Type
number
Description
The code point.
Name
name?
Type
string
Description
The code point's registered name.

TLSExtension

A TLS extension in a ClientHello.

Name
code?
Type
number
Description
The extension type.
Name
name?
Type
string
Description
The extension's registered name.
Name
length?
Type
number
Description
The extension data length in bytes.

HeliosDNSEvent

A DNS tunnel captured by a Helios honeypot.

Name
timestamp
Type
UnixTime
Description
When the tunnel was captured, in Unix milliseconds.
Name
tunnel_id
Type
string
Description
Identifies the proxy tunnel. It is an unsigned 64-bit integer on the wire, kept as its exact decimal digits because a number loses precision above Number.MAX_SAFE_INTEGER.
Name
domain
Type
string
Description
The destination host the tunnel was opened to.
Name
port
Type
number
Description
The destination port.
Name
protocol
Type
"dns"
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 sensor sends none.

Name
session
Type
string
Description
Identifies the ADB session, as 32 hex characters.
Name
sequential_id
Type
number
Description
The 1-based position of the command within its session.
Name
command
Type
string
Description
The shell command as plain text. Invalid UTF-8 bytes become U+FFFD.
Name
hash
Type
string
Description
The SHA-256 the sensor assigns to the session's payload, as 64 hex characters. 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

Each value set is a type alias of string literals. There are no constants, so compare fields with the string values. The sets marked open end in string & {}, which accepts any other string while keeping editor completions, so the API can add values without breaking your types. Handle unknown values instead of assuming an exhaustive switch.

DomainInfo.status, Organization.relation, Export.kind, and ExportMeta.kind are closed unions written inline on the field, as shown in their types.

NetworkType

The kind of network that announces an address. Open.

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

ServiceCategory

The category of a proxy, VPN, or other service seen on an address, used by the type field of ProxyEvent, AnonymizerEvent, and JA4TEvent. 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`

DeviceOS

An operating system seen behind an address. Open.

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

Scope

A permission granted to an API key. 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`

ActivityCadence

The activity pattern of a domain, always one of these sentences.

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.`

ParquetType

The type of a Parquet column. Open.

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

Timestamps

A Unix time as sent by the API.

type UnixTime = number;

Units: It is in seconds, except the timestamp of anonymizer and Helios HTTP, HTTPS, and DNS stream events, which is in milliseconds. AccountAPIKey.created_at is the one RFC 3339 string instead.

toDate converts either unit to a Date.

function toDate(timestamp: UnixTime): Date;

import { toDate } from "@synthient/synthient";

const info = await client.lookupIP("8.8.8.8");
for (const device of info.intelligence?.devices ?? []) {
  console.log(device.os, device.version, toDate(device.last_seen).toISOString());
}

Units: Values of 1e12 or more are read as milliseconds, since as seconds they would be tens of thousands of years away.