# Lookups

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

## LookupIPAsync

Returns intelligence for an IPv4 or IPv6 address.

```csharp
public Task<IPInfo> LookupIPAsync(IPAddress ip, CancellationToken cancellationToken = default)
```

```csharp
var info = await client.LookupIPAsync(IPAddress.Parse("213.149.183.127"));
if (info.Location is not null)
{
    Console.WriteLine($"{info.Location.City} {info.Location.Country}");
}
if (info.Intelligence is not null)
{
    foreach (var provider in info.Intelligence.Providers)
    {
        Console.WriteLine($"{provider.Name} {provider.Type} {provider.LastSeen:u}");
    }
}
```

- **Cost:** Each lookup costs one credit, and failed lookups are not billed.
- **Input:** An IPv6 address with a scope ID, such as `fe80::1%3`, throws an `ArgumentException` without sending a request. Use `IPAddress.TryParse` to validate untrusted input first.
- **Errors:** Private and reserved addresses fail with a 422 `ApiException`.

## LookupIPsAsync

Looks up as many as 1000 addresses in one request.

```csharp
public Task<IReadOnlyList<IPInfo>> LookupIPsAsync(IEnumerable<IPAddress> ips, CancellationToken cancellationToken = default)
```

```csharp
IPAddress[] addresses = [IPAddress.Parse("8.8.8.8"), IPAddress.Parse("1.1.1.1")];
var results = await client.LookupIPsAsync(addresses);
foreach (var result in results)
{
    if (result.Intelligence is null)
    {
        Console.WriteLine($"{result.IP} no intelligence available");
        continue;
    }
    Console.WriteLine($"{result.IP} {result.Intelligence.RiskScore}");
}
```

- **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. Match results by `IP`, which the API canonicalizes, rather than by position.
- **Input:** An empty batch returns an empty list without a request. More than 1000 addresses, a `null` address, or an IPv6 address with a scope ID throws an `ArgumentException` before anything is sent.
- **Errors:** A batch with no address the API can look up fails with a 422 `ApiException`.

## LookupDomainAsync

Returns the honeypot traffic Synthient has observed for a domain.

```csharp
public Task<DomainInfo> LookupDomainAsync(string domain, int? limit = null, CancellationToken cancellationToken = default)
```

```csharp
var domain = await client.LookupDomainAsync("example.com", limit: 10);
Console.WriteLine($"{domain.Status} {domain.Stats.Events24h}");
foreach (var recent in domain.RecentEvents)
{
    Console.WriteLine($"{recent.Timestamp:u} {recent.TargetSubdomain} {recent.Port}");
}
```

- **Cost:** Each lookup costs one credit.
- **Input:** Internationalized names must be sent in Punycode. `limit` caps the number of recent events returned, from 1 to 1000, and `null` uses the API default of 50. An empty domain, `"."`, or `".."` throws an `ArgumentException`, and a `limit` below 1 throws an `ArgumentOutOfRangeException`, without a request.
- **Results:** A domain that has never been observed returns `DomainStatus.Inactive` and zero counts rather than an error.

## Account and health

### GetAccountAsync

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

```csharp
public Task<Account> GetAccountAsync(CancellationToken cancellationToken = default)
```

```csharp
var account = await client.GetAccountAsync();
Console.WriteLine($"{account.Email} {account.Organization.Name} {string.Join(", ", account.Scopes)}");
Console.WriteLine($"{account.LookupQuota.Credits} credits, resetting in {account.LookupQuota.ResetsIn}");
```

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

### CheckHealthAsync

Completes if the API and its dependencies are healthy, and throws a 503 `ApiException` if not.

```csharp
public Task CheckHealthAsync(CancellationToken cancellationToken = default)
```

```csharp
try
{
    await client.CheckHealthAsync();
}
catch (ApiException e)
{
    Console.WriteLine($"unhealthy: {e.StatusCode}");
}
```

- **Cost:** It costs no credits.
- **Errors:** The API does not check the key, but a malformed key fails with a 401 `ApiException`.