Lookups

Look up IP addresses and domains, and check your account and the API's health.

lookupIP

Returns intelligence for an IPv4 or IPv6 address.

lookupIP(ip: string, options?: RequestOptions): Promise<IPInfo>;

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

const info = await client.lookupIP("213.149.183.127");
if (info.location) {
  console.log(info.location.city, info.location.country);
}
for (const provider of info.intelligence?.providers ?? []) {
  console.log(provider.provider, provider.type, toDate(provider.last_seen));
}

• Cost: Each lookup costs one credit, and failed lookups are not billed.
• Input: A string that is not an IP address rejects with a TypeError without sending a request.
• Errors: A private or reserved address rejects with a 422 APIError.

lookupIPs

Looks up as many as 1000 addresses in one request.

lookupIPs(ips: Iterable<string>, options?: RequestOptions): Promise<IPInfo[]>;

const results = await client.lookupIPs(["8.8.8.8", "1.1.1.1"]);
for (const result of results) {
  if (!result.intelligence) {
    console.log(result.ip, "no intelligence available");
    continue;
  }
  console.log(result.ip, result.intelligence.risk_score);
}

• Cost: The API bills ceil(n * 0.9) credits for the n distinct addresses it looks up, and bills nothing if the account cannot cover the whole batch.
• Results: Private and reserved addresses are skipped and duplicates collapse into one result, so there can be fewer results than addresses. Results follow the order each address first appears, and ip holds its canonical form, so match results by ip rather than by position.
• Input: ips can be any iterable of strings, such as an array or a Set. An empty iterable resolves to [] without a request. A string that is not an IP address rejects with a TypeError that names its index, before anything is sent.
• Errors: A batch with no address the API can look up rejects with a 422 APIError. The SDK does not count the addresses; the API rejects a batch of more than 1000 with a 422 APIError.

lookupDomain

Returns the honeypot traffic Synthient has observed for a domain.

lookupDomain(domain: string, options?: LookupDomainOptions): Promise<DomainInfo>;

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

const domain = await client.lookupDomain("example.com", { limit: 10 });
console.log(domain.status, domain.stats.events_24h);
for (const event of domain.recent_events) {
  console.log(toDate(event.timestamp), event.target_subdomain, event.port);
}

• Cost: Each lookup costs one credit.
• Input: Internationalized names must be sent in Punycode. An empty domain, ".", "..", or a string that is not well-formed Unicode rejects with a TypeError without a request.
• Results: A domain that has never been observed resolves with status "inactive" and zeroed stats rather than an error.

Account and health

account

Returns the account that owns the API key, including its scopes and remaining lookup credits.

account(options?: RequestOptions): Promise<Account>;

const account = await client.account();
const { credits, resets_in } = account.lookup_quota;
console.log(account.email, account.organization.name, account.scopes);
console.log(credits, "credits, resetting in", resets_in, "seconds");

• Cost: It costs no credits.

health

Resolves if the API and its dependencies are healthy.

health(options?: RequestOptions): Promise<void>;

await client.health();

• Cost: It costs no credits.
• Errors: An unhealthy API rejects with a 503 APIError. The API does not check the key, but a malformed key rejects with a 401 APIError. Unlike the other free requests, it is retried only on rate limits, so a connection failure rejects at once.