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

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

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

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

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

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

- `LookupDomainOptions.limit?` `number | undefined` — Caps the number of recent events returned. The API default is 50, and it clamps values above 1000. A value that is not a positive integer rejects with a `RangeError` before a request. `LookupDomainOptions` also takes `signal` from `RequestOptions`.

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

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

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

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

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