# Lookups

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

## lookupIp

Looks up an IPv4 or IPv6 address.

```php
public function lookupIp(string $ip): IpInfo
```

```php
$info = $client->lookupIp('213.149.183.127');
if ($info->location !== null) {
    echo $info->location->city, ', ', $info->location->country, "\n";
}
if ($info->intelligence !== null) {
    foreach ($info->intelligence->providers as $provider) {
        echo $provider->name, ' ', $provider->type, ' ', $provider->lastSeen->format(DATE_ATOM), "\n";
    }
}
```

- **Cost:** It costs one credit, and failed lookups are not billed.
- **Input:** A string that is not an IP address throws `\InvalidArgumentException` without sending a request. The address is sent in canonical form.
- **Errors:** Private and reserved addresses are rejected with a 422 `ApiException`.

## lookupIps

Takes a `list<string>` of as many as 1,000 addresses and returns a `list<IpInfo>` from one request.

```php
public function lookupIps(array $ips): array
```

```php
foreach ($client->lookupIps(['8.8.8.8', '1.1.1.1']) as $result) {
    if ($result->intelligence === null) {
        echo $result->ip, " no intelligence available\n";

        continue;
    }
    echo $result->ip, ' ', $result->intelligence->riskScore, "\n";
}
```

- **Cost:** A batch of `n` distinct addresses costs `ceil(n * 0.9)` credits, and nothing is billed when the team cannot cover the whole batch.
- **Results:** The API skips private and reserved addresses and collapses duplicates, so there can be fewer results than addresses. Match results to inputs by their canonical `ip`, not by position.
- **Input:** An empty array returns `[]` without a request. More than `Client::MAX_BATCH_SIZE` addresses, or an invalid address (the message names its index), throws `\InvalidArgumentException` before anything is sent.
- **Errors:** A batch with no address the API can look up, such as one of only private or reserved addresses, is rejected with a 422 `ApiException`.

## lookupDomain

Looks up the proxy traffic Synthient has observed for a domain over the last 30 days.

```php
public function lookupDomain(string $domain, ?int $limit = null): DomainInfo
```

- `limit` `?int` — How many recent events to return. `null` uses the API default of 50, and the API clamps values above 1,000. The top lists are not capped. A value under 1 throws `\InvalidArgumentException`.

```php
$domain = $client->lookupDomain('example.com', limit: 10);
echo $domain->status, ' ', $domain->stats->events24h, "\n";
foreach ($domain->recentEvents as $event) {
    echo $event->timestamp->format(DATE_ATOM), ' ', $event->targetSubdomain, ' ', $event->port, "\n";
}
```

- **Cost:** It costs one credit.
- **Input:** Send internationalized names as Punycode. An empty domain, `"."`, or `".."` throws `\InvalidArgumentException` without a request.
- **Results:** A domain that was never observed is `DomainStatus::INACTIVE` with 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.

```php
public function account(): Account
```

```php
$account = $client->account();
echo $account->email, ' ', $account->organization->name, ' ', implode(', ', $account->scopes), "\n";
echo $account->lookupQuota->credits, ' credits, resetting in ', $account->lookupQuota->resetsIn, " seconds\n";
```

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

### health

Checks that the API is up.

```php
public function health(): void
```

```php
use Synthient\Exception\ApiException;

try {
    $client->health();
} catch (ApiException $e) {
    echo 'unhealthy: ', $e->getMessage(), "\n";
}
```

- **Cost:** It costs no credits.
- **Results:** It returns nothing when the API is healthy and throws an `ApiException` with status 503 when it is not. Like the billed lookups, it is retried only on 429 responses that carry `Retry-After`, so an unhealthy API is reported at once.