# Types

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

## Lookup 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` `netip.Addr` — The address that was looked up.
- `Network` `*Network` — The network that announces the address, or `nil` if the API has no network data.
- `Location` `*Location` — The geolocation of the address, or `nil` if the API has no location data.
- `Intelligence` `*Intelligence` — The risk score and the proxy, VPN, and device observations for the address, or `nil` if the API has no intelligence data.

### Network

- `ASN` `int64` — The autonomous system number, or `0` if the address is not routed.
- `ISP` `string` — The internet service provider that operates the network.
- `Org` `string` — The organization the address is registered to, or empty if unknown.
- `Domain` `string` — The network operator's domain, or empty if unknown.
- `Type` `NetworkType` — The kind of network, such as `NetworkTypeResidential`. See [Enumerations](#enumerations).
- `AbuseEmail` `string` — The operator's abuse contact email, or empty if unknown.
- `AbusePhone` `string` — The operator's abuse contact phone number, or empty if unknown.

### Location

- `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` `float64` — The latitude in degrees.
- `Longitude` `float64` — The longitude in degrees.
- `GeoHash` `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.

- `RiskScore` `int` — 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.

- `Name` `string` — The service tag, such as `"BRIGHTDATA"`. The API names this field `provider`. See [Service Tags](https://docs.synthient.com/service-tags).
- `Type` `string` — The service category.
- `LastSeen` `Timestamp` — When the service was last seen on the address.

### Device

A device type seen behind an address.

- `OS` `OS` — The operating system. See [Enumerations](#enumerations).
- `Version` `string` — The operating system version.
- `LastSeen` `Timestamp` — 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` `DomainStatus` — Whether the domain had events in the last 24 hours.
- `Stats` `DomainStats` — Aggregate event counts.
- `UniqueIPs` `UniqueIPs` — Counts of the distinct source addresses.
- `TimeSeries` `[]TimeSeriesPoint` — Daily event counts.
- `TopASN` `ASNCount` — The network that sent the most events. It is zero when there are no events.
- `TopSubdomains` `[]SubdomainCount` — The most targeted subdomains.
- `TopPorts` `[]PortCount` — The most targeted ports.
- `GeoDistribution` `[]CountryCount` — Event counts by source country.
- `HourDOWHeatmap` `[][]int64` — The last 30 days of events by UTC day of week and hour, indexed as `HourDOWHeatmap[day][hour]`. Day 0 is Monday, unlike `time.Weekday`, where 0 is Sunday.
- `ActivityStats` `ActivityStats` — The hourly activity pattern.
- `RecentEvents` `[]DomainEvent` — The most recent events, capped by `LookupDomainParams.Limit`.

### DomainStats

- `Events24h` `int64` — Events in the last 24 hours.
- `TotalEvents30d` `int64` — Events in the last 30 days.

### UniqueIPs

The distinct source addresses seen for a domain.

- `Value24h` `int64` — Distinct source addresses in the last 24 hours.
- `Value30d` `int64` — Distinct source addresses in the last 30 days.
- `Sparkline24h` `[]int64` — Hourly counts for the last 24 hours.

### TimeSeriesPoint

The event counts for one day.

- `Date` `Timestamp` — The start of the day.
- `Events` `int64` — Events that day.
- `UniqueIPs` `int64` — The number of distinct source addresses that day.

### ASNCount

- `ASN` `int64` — The autonomous system number.
- `Events` `int64` — Events from that network.

### SubdomainCount

- `Subdomain` `string` — The subdomain.
- `Count` `int64` — The number of events that targeted it.

### PortCount

- `Port` `int` — The port.
- `Count` `int64` — The number of events that targeted it.

### CountryCount

- `CountryCode` `string` — The ISO 3166-1 alpha-2 country code.
- `Events` `int64` — Events from that country.
- `UniqueIPs` `int64` — Distinct source addresses from that country.

### ActivityStats

The hourly activity pattern of a domain.

- `Cadence` `Cadence` — How events are spread over the last 30 days. See [Enumerations](#enumerations).
- `MedianPerHour` `int64` — The median number of events per hour.
- `P95PerHour` `int64` — The 95th percentile of events per hour.
- `PeakHour` `int` — The busiest UTC hour of the day.
- `QuietHour` `int` — The quietest UTC hour of the day.

### DomainEvent

A single honeypot event for a domain.

- `Timestamp` `Timestamp` — When the event happened.
- `SourceIP` `string` — The full proxy exit address that carried the event. The API names the field `source_ip_masked`, but the address is not masked.
- `TargetSubdomain` `string` — The subdomain that was targeted.
- `CountryCode` `string` — The source country.
- `Port` `int` — The destination port.

## Account types

### Account

The account that owns the API key.

- `Email` `string` — The account's email address.
- `FirstName` `string` — The account holder's first name.
- `LastName` `string` — The account holder's last name.
- `Organization` `Organization` — The organization the account belongs to.
- `Scopes` `[]Scope` — The permissions granted to the API key. See [Enumerations](#enumerations).
- `LookupQuota` `LookupQuota` — The remaining lookup credit balance.
- `APIKey` `AccountAPIKey` — The API key used for the request.

### Organization

- `ID` `string` — The organization's ID.
- `Name` `string` — The organization's name.
- `Relation` `Relation` — The account's role in the organization. See [Enumerations](#enumerations).

### LookupQuota

An account's lookup credit balance.

- `Credits` `int64` — The number of lookup credits remaining.
- `ResetsIn` `int64` — The number of seconds until the credits reset.

### AccountAPIKey

- `ID` `string` — Identifies the key. It is not the secret key itself.
- `Name` `string` — The key's display name.
- `CreatedAt` `time.Time` — When the key was created.

## Export types

### ExportPage

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

- `Stream` `string` — The feed's stream identifier, such as `"proxies"`.
- `Exports` `[]Export` — The exports on this page. The API names this field `feeds`.
- `NextCursor` `string` — Fetches the next page through `ListExportsParams.Cursor`. It is empty on the last page.

### Export

A Parquet export of a feed.

- `ID` `string` — Identifies the export for `ExportMeta`, `Download`, and `DownloadURL`. On the first page, the newest hourly export may have the ID `LatestExport`.
- `Kind` `ExportKind` — Whether the export covers an hour or a day.
- `Date` `string` — The UTC day of the export as `"YYYY-MM-DD"`.
- `Hour` `*int` — The UTC hour of an hourly export, or `nil` for a daily export.
- `SizeBytes` `int64` — The size of the Parquet file in bytes.
- `RowCount` `int64` — The number of rows in the file.
- `Checksum` `string` — The hex-encoded SHA-256 of the Parquet file.
- `CreatedAt` `Timestamp` — When the export was created.
- `DownloadPath` `string` — The API path of the export's download, including the version prefix.

### ExportMeta

A Parquet export without its contents.

- `ID` `string` — The export ID.
- `Stream` `string` — The feed's stream identifier.
- `Kind` `ExportKind` — Whether the export covers an hour or a day.
- `Format` `string` — The file format, `"parquet"`.
- `Date` `Timestamp` — The start of the export's UTC day or hour.
- `Hour` `*int` — The UTC hour of an hourly export, or `nil` for a daily export.
- `Rows` `int64` — The number of rows in the file.
- `Size` `int64` — The size of the Parquet file in bytes.
- `Checksum` `string` — The hex-encoded SHA-256 of the Parquet file.
- `CreatedAt` `Timestamp` — When the export was created.
- `Schema` `ParquetSchema` — The Parquet columns.

### ParquetSchema

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

### ParquetColumn

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

## Event types

Stream payloads match the [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/helios) documentation field for field. Fields the API omits are left at their zero value.

### ProxyEvent

A proxy sighting from the `Proxies` feed.

- `IP` `string` — The proxy exit address.
- `Provider` `string` — The proxy service tag.
- `Type` `ProxyType` — The service category. See [Enumerations](#enumerations).
- `CountryCode` `string` — The ISO 3166-1 alpha-2 country of the address.
- `ASN` `int64` — The autonomous system number of the address.
- `Timestamp` `Timestamp` — When the proxy was seen, in Unix seconds.

### AnonymizerEvent

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

- `RangeStart` `string` — The first address of the range.
- `RangeEnd` `string` — The last address of the range.
- `Provider` `string` — The service tag.
- `Type` `ProxyType` — The service category, such as `ProxyTypeCommercialVPN`.
- `CountryCode` `string` — The ISO 3166-1 alpha-2 country of `RangeStart`.
- `ASN` `int64` — The autonomous system number of `RangeStart`.
- `Timestamp` `Timestamp` — When the range was seen, in Unix milliseconds.

### TorrentEvent

A torrent observed on the BitTorrent DHT or a tracker.

- `InfoHash` `string` — The hex-encoded SHA-1 info hash.
- `Name` `string` — The torrent's name.
- `MagnetURI` `string` — The torrent's magnet link.
- `TotalSize` `int64` — The total size of the torrent's files in bytes.
- `PieceLength` `int64` — The piece size in bytes.
- `FileCount` `int` — The number of files in the torrent.
- `Files` `[]TorrentFile` — The files in the torrent.
- `Peers` `[]TorrentPeer` — The peers seen sharing the torrent.
- `Timestamp` `Timestamp` — When the torrent was seen, in Unix seconds.

### TorrentFile

- `Path` `string` — The file path within the torrent.
- `Length` `int64` — The file size in bytes.

### TorrentPeer

- `IP` `string` — The peer's address.
- `Port` `int` — The peer's port.
- `Source` `string` — Where the peer was found, such as `"DHT"`, `"PEX"`, or `"tracker"`.
- `Encrypted` `bool` — 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` `ProxyType` — The service category, such as `ProxyTypeDatacenterProxy`.
- `CountryCode` `string` — The ISO 3166-1 alpha-2 country of the address.
- `ASN` `int64` — The autonomous system number of the address.
- `Timestamp` `Timestamp` — When the fingerprint was seen, in Unix seconds.

### HeliosMeta

The Helios honeypot sensor that captured an event.

- `ProxyIP` `string` — The proxy exit address the traffic arrived through.
- `Server` `string` — The sensor that captured the traffic.
- `PoolID` `string` — The sensor pool.
- `Provider` `string` — The proxy service the traffic arrived through.

### HeliosHTTPEvent

An HTTP request captured by a Helios honeypot.

- `Timestamp` `Timestamp` — When the request was captured, in Unix milliseconds.
- `TunnelID` `uint64` — Identifies the proxy tunnel the request arrived through. Live values use the full `uint64` range.
- `Domain` `string` — The host the tunnel was opened to.
- `Port` `int` — The destination port.
- `Protocol` `string` — Always `"http"`.
- `Meta` `HeliosMeta` — The capturing sensor.
- `Details` `HTTPRequestDetails` — The parsed request. It is a struct value, so it is the zero `HTTPRequestDetails` when the API omits it or sends `null`.
- `Raw` `[]byte` — The raw request bytes, decoded from the API's base64.

### 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` `map[string]string` — The request headers.

### HeliosHTTPSEvent

A TLS ClientHello captured by a Helios honeypot.

- `Timestamp` `Timestamp` — When the handshake was captured, in Unix milliseconds.
- `TunnelID` `uint64` — Identifies the proxy tunnel the handshake arrived through. Live values use the full `uint64` range.
- `Domain` `string` — The host the tunnel was opened to.
- `Port` `int` — The destination port.
- `Protocol` `string` — Always `"https"`.
- `Meta` `HeliosMeta` — The capturing sensor.
- `Details` `*TLSClientHello` — The parsed ClientHello, or `nil` if the sensor could not parse the handshake.
- `Raw` `string` — Always empty, because the sensors do not capture handshake bytes.

### TLSClientHello

A TLS ClientHello parsed by a Helios sensor. Fields the sensor could not parse are empty.

- `RecordVersion` `string` — The record layer version, such as `"TLS 1.0"`.
- `HandshakeVersion` `string` — The ClientHello version, such as `"TLS 1.2"`.
- `ClientRandom` `string` — The hex-encoded 32-byte client random.
- `SessionID` `string` — The hex-encoded session ID.
- `SessionIDLength` `int` — The length of the session ID in bytes.
- `CipherSuites` `[]TLSCodeName` — The offered cipher suites.
- `CompressionMethods` `[]int` — The offered compression methods.
- `Extensions` `[]TLSExtension` — The extensions in wire order.
- `SNI` `string` — The `server_name` extension value.
- `ALPN` `[]string` — The offered application protocols.
- `SupportedVersions` `[]string` — The offered TLS versions.
- `SupportedGroups` `[]TLSCodeName` — The offered key exchange groups.
- `SignatureAlgorithms` `[]TLSCodeName` — The offered signature algorithms.
- `ECPointFormats` `[]string` — The offered elliptic curve point formats.
- `KeyShareGroups` `[]string` — The groups the client sent key shares for.
- `PSKKeyExchangeModes` `[]string` — The offered pre-shared key exchange modes.
- `CompressCertificate` `[]string` — The offered certificate compression algorithms.
- `HasGREASE` `bool` — Whether the ClientHello contains GREASE values.
- `ApplicationSettings` `bool` — Whether the client offered application settings (ALPS).
- `DelegatedCredentials` `bool` — Whether the client offered the `delegated_credentials` extension.
- `EncryptThenMAC` `bool` — Whether the client offered the `encrypt_then_mac` extension.
- `ExtendedMasterSecret` `bool` — Whether the client offered the `extended_master_secret` extension.
- `PostHandshakeAuth` `bool` — Whether the client offered the `post_handshake_auth` extension.
- `RenegotiationInfo` `bool` — Whether the client offered the `renegotiation_info` extension.
- `SignedCertificateTimestamps` `bool` — Whether the client offered the `signed_certificate_timestamp` extension.
- `StatusRequest` `bool` — Whether the client requested OCSP stapling.

### TLSCodeName

A TLS registry code point and its name. GREASE values are named `"GREASE(0x....)"`.

- `Code` `int` — The code point.
- `Name` `string` — The code point's registered name.

### TLSExtension

An extension in a TLS ClientHello.

- `Code` `int` — The extension type.
- `Name` `string` — The extension's registered name.
- `Length` `int` — The extension body length in bytes.

### HeliosDNSEvent

A destination that a Helios honeypot tunnel was asked to reach. Despite the feed's name, it is not a DNS query: names resolved inside a tunneled DNS session are not visible.

- `Timestamp` `Timestamp` — When the event was captured, in Unix milliseconds.
- `TunnelID` `uint64` — Identifies the proxy tunnel. Live values use the full `uint64` range.
- `Domain` `string` — The host name or address literal the tunnel was opened to.
- `Port` `int` — The destination port.
- `Protocol` `string` — 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.
- `SequentialID` `int64` — The 1-based position of the command within its session.
- `Command` `string` — The shell command. Invalid UTF-8 bytes are replaced with U+FFFD.
- `Hash` `string` — 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

Each value set is a named `string` type with a constant per known value. The API may add values to the sets marked open, so handle unknown values instead of assuming a closed switch.

### NetworkType

The kind of network that announces an address. Open.

| Constant                  | Value            |
| ------------------------- | ---------------- |
| `NetworkTypeMobile`       | `MOBILE`         |
| `NetworkTypeSatellite`    | `SATELLITE`      |
| `NetworkTypeInFlightWiFi` | `IN_FLIGHT_WIFI` |
| `NetworkTypeResidential`  | `RESIDENTIAL`    |
| `NetworkTypeCorporate`    | `CORPORATE`      |
| `NetworkTypeAcademic`     | `ACADEMIC`       |
| `NetworkTypeDatacenter`   | `DATACENTER`     |
| `NetworkTypeGovernment`   | `GOVERNMENT`     |

### ProxyType

The kind of service seen on an address. Open.

| Constant                    | Value               |
| --------------------------- | ------------------- |
| `ProxyTypeFreeVPN`          | `FREE_VPN`          |
| `ProxyTypeCommercialVPN`    | `COMMERCIAL_VPN`    |
| `ProxyTypeEnterpriseVPN`    | `ENTERPRISE_VPN`    |
| `ProxyTypeMobileProxy`      | `MOBILE_PROXY`      |
| `ProxyTypeBlockchainProxy`  | `BLOCKCHAIN_PROXY`  |
| `ProxyTypeResidentialProxy` | `RESIDENTIAL_PROXY` |
| `ProxyTypePublicProxy`      | `PUBLIC_PROXY`      |
| `ProxyTypeDatacenterProxy`  | `DATACENTER_PROXY`  |
| `ProxyTypeTorNode`          | `TOR_NODE`          |
| `ProxyTypePrivateRelay`     | `PRIVATE_RELAY`     |
| `ProxyTypeBotnet`           | `BOTNET`            |
| `ProxyTypeSearchEngine`     | `SEARCH_ENGINE`     |
| `ProxyTypeAICrawler`        | `AI_CRAWLER`        |
| `ProxyTypeSocialMedia`      | `SOCIAL_MEDIA`      |
| `ProxyTypeUptimeMonitor`    | `UPTIME_MONITOR`    |
| `ProxyTypeLinkPreview`      | `LINK_PREVIEW`      |
| `ProxyTypeSEOCrawler`       | `SEO_CRAWLER`       |
| `ProxyTypeWebArchiver`      | `WEB_ARCHIVER`      |
| `ProxyTypeWebhookProvider`  | `WEBHOOK_PROVIDER`  |
| `ProxyTypePaymentProcessor` | `PAYMENT_PROCESSOR` |
| `ProxyTypeInternetScanner`  | `INTERNET_SCANNER`  |

### OS

A device operating system. Open.

| Constant     | Value       |
| ------------ | ----------- |
| `OSAndroid`  | `Android`   |
| `OSChromeOS` | `Chrome OS` |
| `OSFreeBSD`  | `FreeBSD`   |
| `OSiOS`      | `iOS`       |
| `OSLinux`    | `Linux`     |
| `OSMacOSX`   | `Mac OS X`  |
| `OSWindows`  | `Windows`   |

### Scope

A permission granted to an API key. Open. `ScopeBasic` 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/go/feeds). See [Authentication](https://docs.synthient.com/authentication) for how scopes are granted.

| Constant                   | Value                   |
| -------------------------- | ----------------------- |
| `ScopeBasic`               | `BASIC`                 |
| `ScopeProxyFeeds`          | `PROXY_FEEDS`           |
| `ScopeProxyFirehose`       | `PROXY_FIREHOSE`        |
| `ScopeAnonymizersFeed`     | `ANONYMIZERS_FEED`      |
| `ScopeAnonymizersStream`   | `ANONYMIZERS_STREAM`    |
| `ScopeJA3Feed`             | `JA3_FEED`              |
| `ScopeJA3Stream`           | `JA3_STREAM`            |
| `ScopeTorrentsFeed`        | `TORRENTS_FEED`         |
| `ScopeTorrentsStream`      | `TORRENTS_STREAM`       |
| `ScopeHoneypotHTTPFeed`    | `HONEYPOT_HTTP_FEED`    |
| `ScopeHoneypotHTTPStream`  | `HONEYPOT_HTTP_STREAM`  |
| `ScopeHoneypotHTTPSFeed`   | `HONEYPOT_HTTPS_FEED`   |
| `ScopeHoneypotHTTPSStream` | `HONEYPOT_HTTPS_STREAM` |
| `ScopeHoneypotADBFeed`     | `HONEYPOT_ADB_FEED`     |
| `ScopeHoneypotADBStream`   | `HONEYPOT_ADB_STREAM`   |
| `ScopeHoneypotDNSFeed`     | `HONEYPOT_DNS_FEED`     |
| `ScopeHoneypotDNSStream`   | `HONEYPOT_DNS_STREAM`   |
| `ScopeJA4Feed`             | `JA4_FEED`              |
| `ScopeJA4Stream`           | `JA4_STREAM`            |
| `ScopeJA4TFeed`            | `JA4T_FEED`             |
| `ScopeJA4TStream`          | `JA4T_STREAM`           |
| `ScopeAdminProxies`        | `ADMIN_PROXIES`         |

### Relation

An account's role in its organization.

| Constant         | Value    |
| ---------------- | -------- |
| `RelationOwner`  | `OWNER`  |
| `RelationAdmin`  | `ADMIN`  |
| `RelationMember` | `MEMBER` |

### DomainStatus

Whether a domain has recent activity.

| Constant               | Value      | Meaning                                                                    |
| ---------------------- | ---------- | -------------------------------------------------------------------------- |
| `DomainStatusActive`   | `active`   | The domain had events in the last 24 hours.                                |
| `DomainStatusInactive` | `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.

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

### ExportKind

Whether an export covers an hour or a day.

| Constant           | Value    |
| ------------------ | -------- |
| `ExportKindHourly` | `hourly` |
| `ExportKindDaily`  | `daily`  |

### ParquetType

The type of a Parquet column. Open.

| Constant            | Value    |
| ------------------- | -------- |
| `ParquetTypeString` | `string` |
| `ParquetTypeInt64`  | `int64`  |
| `ParquetTypeUint32` | `uint32` |
| `ParquetTypeUint64` | `uint64` |
| `ParquetTypeBool`   | `bool`   |
| `ParquetTypeBytes`  | `bytes`  |

## Timestamps

A Unix time as encoded by the API.

```go
type Timestamp int64
```

- **Units:** It is in seconds, except on anonymizer and Helios HTTP, HTTPS, and DNS stream events, where it is in milliseconds.

`Time` converts either unit to a `time.Time` in UTC.

```go
func (t Timestamp) Time() time.Time
```

- **Units:** Values of `1e12` or more are read as milliseconds.
- **Zero value:** The zero `Timestamp` returns the zero `time.Time`, so absent timestamps report `IsZero`.