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

```java
public IpInfo lookupIp(String ip)
```

```java
IpInfo info = client.lookupIp("213.149.183.127");
Location location = info.location();
if (location != null) {
    System.out.println(location.city() + ", " + location.country());
}
Intelligence intelligence = info.intelligence();
if (intelligence != null) {
    for (Provider provider : intelligence.providers()) {
        System.out.println(provider.name() + " " + provider.type() + " " + provider.lastSeen());
    }
}
```

- **Cost:** Each lookup costs one credit, and failed lookups are not billed.
- **Input:** A string that is not an address literal throws `IllegalArgumentException` without sending a request, and host names are never resolved.
- **Errors:** Private and reserved addresses return a 422 `ApiException`.

## lookupIps

Looks up as many as 1000 addresses in one request.

```java
public List<IpInfo> lookupIps(Collection<String> ips)
```

```java
List<IpInfo> results = client.lookupIps(List.of("8.8.8.8", "1.1.1.1"));
for (IpInfo result : results) {
    Intelligence intelligence = result.intelligence();
    if (intelligence == null) {
        System.out.println(result.ip() + " no intelligence available");
        continue;
    }
    System.out.println(result.ip() + " " + intelligence.riskScore());
}
```

- **Cost:** The API bills `ceil(n * 0.9)` credits for the `n` distinct addresses it looks up, and bills nothing if the team or key cannot cover the whole batch.
- **Results:** Private and reserved addresses are skipped and duplicates are merged, so there can be fewer results than addresses, in a different order. Match results by `ip()`, which the API canonicalizes, rather than by position.
- **Input:** An empty collection returns an empty list without a request. More than 1000 addresses, or an element that is `null` or not an address literal, throws `IllegalArgumentException` before anything is sent.
- **Errors:** A batch with no address the API can look up returns a 422 `ApiException`.

## lookupDomain

Returns the proxy traffic to a domain that Synthient's honeypots observed over the last 30 days.

```java
public DomainInfo lookupDomain(String domain)
public DomainInfo lookupDomain(String domain, int limit)
```

```java
DomainInfo domain = client.lookupDomain("example.com", 10);
System.out.println(domain.status() + " " + domain.stats().events24h());
for (DomainEvent event : domain.recentEvents()) {
    System.out.println(event.timestamp() + " " + event.targetSubdomain() + " " + event.port());
}
```

- **Cost:** Each lookup costs one credit.
- **Limit:** `limit` caps the number of recent events, and the API clamps it to 1000. Without it, the API returns its default of 50.
- **Input:** Internationalized names must be in Punycode. An empty domain, `"."`, or `".."`, or a limit below 1, throws `IllegalArgumentException` without a request.
- **Results:** A domain that has never been observed returns `DomainStatus.INACTIVE` and zeroed statistics rather than an error.

## Account and health

### account

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

```java
public Account account()
```

```java
Account account = client.account();
System.out.println(account.email() + " " + account.organization().name() + " " + account.scopes());
LookupQuota quota = account.lookupQuota();
System.out.println(quota.credits() + " credits, resetting in " + quota.resetsIn());
```

- **Cost:** It costs no credits.

### health

Returns normally if the API and its dependencies are healthy.

```java
public void health()
```

```java
try {
    client.health();
} catch (ApiException e) {
    System.err.println("unhealthy: " + e.statusCode());
}
```

- **Errors:** An unhealthy API throws an `ApiException` with status 503. The API does not check the key, but a malformed key throws a 401 `ApiException`.