# 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](https://docs.synthient.com/ipapi) for how each field is derived.

- `ip` `string` — The address that was looked up.
- `network?` `Network` — The network that announces the address. Absent when the API has no network data.
- `location?` `Location` — The geolocation of the address. Absent when the API has no location data.
- `intelligence?` `Intelligence` — 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.

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

### Location

The geolocation of an address.

- `country` `string` — The ISO 3166-1 alpha-2 country code.
- `state` `string` — The state or region.
- `city` `string` — The city.
- `timezone` `string` — The IANA time zone name.
- `latitude` `number` — The latitude in degrees.
- `longitude` `number` — The longitude in degrees.
- `geo_hash` `string` — 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` `number` — The risk of the address, from 0 to 100.
- `categories` `string[]` — The kinds of services seen on the address, such as `"RESIDENTIAL_PROXY"`. New values may be added.
- `behavior` `string[]` — Behaviors observed from the address. New values may be added.
- `providers` `Provider[]` — The proxy, VPN, and anonymizer services seen using the address. An empty list does not mean the address is clean.
- `devices` `Device[]` — The device types seen behind the address.

### Provider

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

- `provider` `string` — The service tag, such as `"BRIGHTDATA"`. See [Service Tags](https://docs.synthient.com/service-tags).
- `type` `string` — The service category.
- `last_seen` `UnixTime` — When the service was last seen using the address.

### Device

A device type seen behind an address.

- `os` `DeviceOS` — The operating system. See [Enumerations](#enumerations).
- `version` `string` — The operating system version.
- `last_seen` `UnixTime` — When the device was last seen.

## Domain types

### DomainInfo

The honeypot traffic Synthient has observed for a domain.

- `domain` `string` — The domain that was looked up.
- `status` `"active" | "inactive"` — `"active"` when the domain had events in the last 24 hours. A domain that was never observed is `"inactive"` with zeroed stats.
- `stats` `DomainStats` — Aggregate event counts.
- `unique_ips` `UniqueIPs` — Counts of the distinct source addresses.
- `time_series` `TimeSeriesPoint[]` — Daily event counts.
- `top_asn?` `ASNCount` — The network that sent the most events. Absent when there are no events.
- `top_subdomains` `SubdomainCount[]` — The most targeted subdomains.
- `top_ports` `PortCount[]` — The most targeted ports.
- `geo_distribution` `CountryCount[]` — Event counts by source country.
- `hour_dow_heatmap` `number[][]` — 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.
- `activity_stats` `ActivityStats` — The hourly activity pattern.
- `recent_events` `DomainEvent[]` — The most recent events, capped by `LookupDomainOptions.limit`.

### DomainStats

Aggregate event counts for a domain.

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

### UniqueIPs

The distinct source addresses seen for a domain.

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

### TimeSeriesPoint

The event counts for one day.

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

### ASNCount

An autonomous system and its event count.

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

### SubdomainCount

A subdomain and its event count.

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

### PortCount

A port and its event count.

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

### CountryCount

A source country and its counts.

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

### ActivityStats

The hourly activity pattern of a domain.

- `cadence` `ActivityCadence` — How events are distributed over time. See [Enumerations](#enumerations).
- `median_per_hour` `number` — The median number of events per hour.
- `p95_per_hour` `number` — The 95th percentile of events per hour.
- `peak_hour` `number` — The busiest UTC hour of the day.
- `quiet_hour` `number` — The quietest UTC hour of the day.

### DomainEvent

A single honeypot event for a domain.

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

## Account types

### Account

The account that owns an API key.

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

### Organization

The organization an account belongs to.

- `id` `string` — The organization's ID.
- `name` `string` — The organization's name.
- `relation` `"OWNER" | "ADMIN" | "MEMBER"` — The account's role in the organization.

### LookupQuota

The lookup credits available to an account.

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

### AccountAPIKey

The API key a request was made with.

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

## Export types

### ExportPage

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

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

### Export

A Parquet export of a feed.

- `id` `string` — 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`.
- `kind` `"hourly" | "daily"` — Whether the export covers a UTC day or a UTC hour.
- `date` `string` — The UTC day of the export as `"YYYY-MM-DD"`.
- `hour?` `number | null` — The UTC hour of an hourly export. Absent or `null` for a daily export.
- `size_bytes` `number` — The size of the Parquet file in bytes.
- `row_count` `number` — The number of rows in the file.
- `checksum` `string` — The hex-encoded SHA-256 of the Parquet file.
- `created_at` `UnixTime` — When the export was created.
- `download_path` `string` — The API path of the export's download, including the version prefix.

### ExportMeta

A Parquet export's metadata, without its contents.

- `id` `string` — The export ID.
- `stream` `string` — The feed's stream identifier.
- `kind` `"hourly" | "daily"` — Whether the export covers a UTC day or a UTC hour.
- `format` `"parquet"` — The file format, always `"parquet"`.
- `date` `UnixTime` — The start of the export: midnight UTC for a daily export, the hour for an hourly one. Unlike `Export.date`, it is a number.
- `hour?` `number | null` — The UTC hour of an hourly export. Absent or `null` for a daily export.
- `rows` `number` — The number of rows in the file.
- `size` `number` — The size of the Parquet file in bytes.
- `checksum` `string` — The hex-encoded SHA-256 of the Parquet file.
- `created_at` `UnixTime` — When the export was created.
- `schema` `ParquetSchema` — The Parquet columns.

### ParquetSchema

The columns of a Parquet export.

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

### ParquetColumn

A column of a Parquet export.

- `name` `string` — The column name.
- `type` `ParquetType` — The column type. See [Enumerations](#enumerations).

## Event types

Event fields keep the stream's JSON names. See [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/helios) for the payloads. Fields the API omits are absent.

### ProxyEvent

A proxy sighting from the `proxies` feed.

- `ip?` `string` — The proxy exit address.
- `provider?` `string` — The proxy service tag.
- `type?` `ServiceCategory` — The service category. See [Enumerations](#enumerations).
- `country_code?` `string` — The ISO 3166-1 alpha-2 country of the address.
- `asn?` `number` — The autonomous system number of the address.
- `timestamp?` `UnixTime` — When the proxy was seen, in Unix seconds.

### AnonymizerEvent

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

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

### TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker.

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

### TorrentFile

A file in a torrent.

- `path?` `string` — The file path within the torrent.
- `length?` `number` — The file size in bytes.

### TorrentPeer

A peer seen sharing a torrent.

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

### JA4TEvent

A JA4T TCP fingerprint sighting.

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

### HeliosMeta

The Helios honeypot sensor that captured an event.

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

### HeliosHTTPEvent

An HTTP request captured by a Helios honeypot.

- `timestamp` `UnixTime` — When the request was captured, in Unix milliseconds.
- `tunnel_id` `string` — 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`.
- `domain` `string` — The destination host the tunnel was opened to.
- `port` `number` — The destination port.
- `protocol` `"http"` — Always `"http"`.
- `meta` `HeliosMeta` — The capturing sensor.
- `details?` `HTTPRequestDetails` — The parsed request.
- `raw?` `string` — The raw request bytes, base64-encoded as the API sends them.

### HTTPRequestDetails

A parsed HTTP request.

- `method?` `string` — The request method.
- `uri?` `string` — The request target.
- `version?` `string` — The HTTP version, such as `"HTTP/1.1"`.
- `headers?` `Record<string, string>` — The request headers.

### HeliosHTTPSEvent

A TLS ClientHello captured by a Helios honeypot.

- `timestamp` `UnixTime` — When the handshake was captured, in Unix milliseconds.
- `tunnel_id` `string` — 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`.
- `domain` `string` — The destination host the tunnel was opened to.
- `port` `number` — The destination port.
- `protocol` `"https"` — Always `"https"`.
- `meta` `HeliosMeta` — The capturing sensor.
- `details?` `TLSClientHello | null` — The parsed ClientHello, or `null` when the sensor could not parse the handshake.
- `raw?` `string | null` — 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.

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

- `code?` `number` — The code point.
- `name?` `string` — The code point's registered name.

### TLSExtension

A TLS extension in a ClientHello.

- `code?` `number` — The extension type.
- `name?` `string` — The extension's registered name.
- `length?` `number` — The extension data length in bytes.

### HeliosDNSEvent

A DNS tunnel captured by a Helios honeypot.

- `timestamp` `UnixTime` — When the tunnel was captured, in Unix milliseconds.
- `tunnel_id` `string` — 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`.
- `domain` `string` — The destination host the tunnel was opened to.
- `port` `number` — The destination port.
- `protocol` `"dns"` — 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 sensor sends none.

- `session` `string` — Identifies the ADB session, as 32 hex characters.
- `sequential_id` `number` — The 1-based position of the command within its session.
- `command` `string` — The shell command as plain text. Invalid UTF-8 bytes become U+FFFD.
- `hash` `string` — 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](https://docs.synthient.com/sdks/node/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`         |

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

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

```ts
function toDate(timestamp: UnixTime): Date;
```

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