# 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](#event-types).

### IPInfo

The intelligence Synthient holds for an IP address. See the [IP API](https://docs.synthient.com/ipapi) for how each field is derived.

- `ip` `IPv4Address | IPv6Address` — The address that was looked up.
- `network` `Network | None` — The network that announces the address, or `None` if the API has no network data.
- `location` `Location | None` — The geolocation of the address, or `None` if the API has no location data.
- `intelligence` `Intelligence | None` — 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.

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

### Location

The geolocation of an address.

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

### Intelligence

Synthient's assessment of an address. See [Methodology](https://docs.synthient.com/methodology) for how it is built.

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

### Provider

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

- `name` `str` — The service tag, such as `"BRIGHTDATA"`. The API names this field `provider`. See [Service Tags](https://docs.synthient.com/service-tags).
- `type` `str` — The service category.
- `last_seen` `datetime` — When the service was last seen on the address.

### Device

A device type seen behind an address.

- `os` `str` — The operating system, such as `"Android"`, `"iOS"`, or `"Windows"`. See [Enumerations](#enumerations).
- `version` `str` — The operating system version.
- `last_seen` `datetime` — When the device was last seen.

## Domain types

### DomainInfo

The honeypot traffic Synthient has observed for a domain.

- `domain` `str` — The domain that was looked up.
- `status` `str` — `"active"` when the domain had events in the last 24 hours, otherwise `"inactive"`. See [Enumerations](#enumerations).
- `stats` `DomainStats` — Aggregate event counts.
- `unique_ips` `UniqueIPs` — Counts of the distinct source addresses.
- `time_series` `list[TimeSeriesPoint]` — Daily event counts.
- `top_asn` `ASNCount | None` — The network that sent the most events, or `None` when there are no events.
- `top_subdomains` `list[SubdomainCount]` — The most targeted subdomains.
- `top_ports` `list[PortCount]` — The most targeted ports.
- `geo_distribution` `list[CountryCount]` — Event counts by source country.
- `hour_dow_heatmap` `list[list[int]]` — 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()`.
- `activity_stats` `ActivityStats` — The hourly activity pattern.
- `recent_events` `list[DomainEvent]` — The most recent events, capped by the `limit` passed to `lookup_domain`.

### DomainStats

Aggregate event counts for a domain.

- `events_24h` `int` — Events in the last 24 hours.
- `total_events_30d` `int` — Events in the last 30 days.

### UniqueIPs

The distinct source addresses seen for a domain.

- `value_24h` `int` — Distinct source addresses in the last 24 hours.
- `value_30d` `int` — Distinct source addresses in the last 30 days.
- `sparkline_24h` `list[int]` — Hourly counts for the last 24 hours.

### TimeSeriesPoint

The event counts for one day.

- `date` `datetime` — The start of the day.
- `events` `int` — Events that day.
- `unique_ips` `int` — The number of distinct source addresses that day.

### ASNCount

An autonomous system and its event count.

- `asn` `int` — The autonomous system number.
- `events` `int` — Events from that network.

### SubdomainCount

A subdomain and its event count.

- `subdomain` `str` — The subdomain.
- `count` `int` — The number of events that targeted it.

### PortCount

A port and its event count.

- `port` `int` — The port.
- `count` `int` — The number of events that targeted it.

### CountryCount

A source country and its counts.

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

### ActivityStats

The hourly activity pattern of a domain.

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

### DomainEvent

A single honeypot event for a domain.

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

## Account types

### Account

The account that owns an API key.

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

### Organization

The organization an account belongs to.

- `id` `str` — The organization's ID.
- `name` `str` — The organization's name.
- `relation` `str` — The account's role, such as `"OWNER"`, `"ADMIN"`, or `"MEMBER"`. See [Enumerations](#enumerations).

### LookupQuota

The lookup credits available to an account.

- `credits` `int` — The number of lookup credits remaining.
- `resets_in` `int` — The number of seconds until the credits reset.

### AccountAPIKey

The API key a request was made with.

- `id` `str` — Identifies the key. It is not the secret key itself.
- `name` `str` — The key's display name.
- `created_at` `datetime` — 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.

- `stream` `str` — The feed's stream identifier, such as `"proxies"`.
- `exports` `list[Export]` — The exports on this page. The API names this field `feeds`.
- `next_cursor` `str | None` — 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.

- `id` `str` — 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"`.
- `kind` `str` — Either `"hourly"` or `"daily"`.
- `date` `date` — The UTC day of the export.
- `hour` `int | None` — The UTC hour of an hourly export, or `None` for a daily export.
- `size_bytes` `int` — The size of the Parquet file in bytes.
- `row_count` `int` — The number of rows in the file.
- `checksum` `str` — The hex-encoded SHA-256 of the Parquet file.
- `created_at` `datetime` — When the export was created.
- `download_path` `str` — The API path of the export's download, including the version prefix.

### ExportMeta

A Parquet export's metadata, without its contents.

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

### ParquetSchema

The columns of a Parquet export.

- `fields` `list[ParquetColumn]` — The columns in file order.

### ParquetColumn

A column of a Parquet export.

- `name` `str` — The column name.
- `type` `str` — The column type, such as `"string"` or `"int64"`. See [Enumerations](#enumerations).

## Event types

Stream payloads follow the [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/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.

- `ip` `str | None` — The proxy exit address.
- `provider` `str | None` — The proxy service tag.
- `type` `str | None` — The service category, such as `"RESIDENTIAL_PROXY"`. See [Enumerations](#enumerations).
- `country_code` `str | None` — The ISO 3166-1 alpha-2 country of the address.
- `asn` `int | None` — The autonomous system number of the address.
- `timestamp` `datetime | None` — When the proxy was seen.

### AnonymizerEvent

A VPN or anonymizer IP range from the `anonymizers` feed.

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

### TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker.

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

### TorrentFile

A file in a torrent.

- `path` `str | None` — The file path within the torrent.
- `length` `int | None` — The file size in bytes.

### TorrentPeer

A peer seen sharing a torrent.

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

### JA4TEvent

A JA4T TCP fingerprint sighting.

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

### HeliosMeta

The Helios honeypot sensor that captured an event.

- `proxy_ip` `str | None` — The proxy exit address the traffic arrived through.
- `server` `str | None` — The sensor that captured the traffic.
- `pool_id` `str | None` — The sensor pool.
- `provider` `str | None` — The proxy service the traffic arrived through.

### HeliosHTTPEvent

An HTTP request captured by a Helios honeypot.

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

### HTTPRequestDetails

A parsed HTTP request.

- `method` `str | None` — The request method.
- `uri` `str | None` — The request target.
- `version` `str | None` — The HTTP version, such as `"HTTP/1.1"`.
- `headers` `dict[str, str] | None` — The request headers.

### HeliosHTTPSEvent

A TLS ClientHello captured by a Helios honeypot.

- `timestamp` `datetime` — When the handshake was captured.
- `tunnel_id` `int` — Identifies the proxy tunnel the handshake arrived through.
- `domain` `str` — The destination host the tunnel was opened to.
- `port` `int` — The destination port.
- `protocol` `str` — Always `"https"`.
- `meta` `HeliosMeta` — The capturing sensor.
- `details` `TLSClientHello | None` — The parsed ClientHello, or `None` when the sensor could not parse the handshake.
- `raw` `str | None` — 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.

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

### TLSCodeName

A TLS registry code point and its name.

- `code` `int | None` — The code point.
- `name` `str | None` — The registered name. GREASE values read as `"GREASE(0x....)"`.

### TLSExtension

A TLS extension in a ClientHello.

- `code` `int | None` — The extension type.
- `name` `str | None` — The extension's registered name.
- `length` `int | None` — 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.

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

### HeliosADBEvent

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

- `session` `str` — Identifies the ADB session as 32 hex characters.
- `sequential_id` `int` — The 1-based position of the command within its session.
- `command` `str` — The shell command as plain text. Invalid UTF-8 bytes are replaced with U+FFFD.
- `hash` `str` — 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](https://docs.synthient.com/sdks/python/feeds). See [Authentication](https://docs.synthient.com/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`  |