v4

Lookups

View as markdown

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

lookupIp

Looks up an IPv4 or IPv6 address.

public function lookupIp(string $ip): IpInfo

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

public function lookupIps(array $ips): array

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.

public function lookupDomain(string $domain, ?int $limit = null): DomainInfo
  • Name
    limit
    Type
    ?int
    Description

    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.

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

public function account(): Account

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

public function health(): void

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.
Previous
Next