# Python SDK

The official Python client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports, with sync and async clients.

> **Note**: The package is published on [PyPI](https://pypi.org/project/synthient/), and every class and method also carries a docstring. These pages cover the same surface with examples. The source and runnable programs (in `examples/`) are at [github.com/synthient/synthient-python](https://github.com/synthient/synthient-python).

## Getting started

### 1. Install

```bash
pip install synthient
```

Requires Python 3.11 or later. The package is named `synthient` and ships type hints. It depends on `httpx`, `pydantic` 2, and `anyio`. The [gRPC schema](https://docs.synthient.com/sdks/python/grpc-schema) fetcher is the `synthient.grpcschema` module, which needs the `grpc` extra:

```bash
pip install 'synthient[grpc]'
```

### 2. Make your first lookup

This program creates a client and looks up one address. Each lookup costs one credit.

```python
import synthient

with synthient.Client() as client:
    info = client.lookup_ip("8.8.8.8")
    if info.network is not None:
        print(info.network.isp, info.network.type)
    if info.intelligence is not None:
        print(info.intelligence.risk_score, info.intelligence.categories)
```

`Client()` reads the API key from the `SYNTHIENT_API_KEY` environment variable. `IPInfo.network`, `IPInfo.location`, and `IPInfo.intelligence` are `None` when the API has no data for that section, so check them before reading their fields.

A `with` block on `Client`, or an `async with` block on `AsyncClient`, closes the client on exit. Steps 3 and 4 reuse the open `client`, so run them inside the `with` block. The async client is used the same way, with `await` on every method. See [Client](https://docs.synthient.com/sdks/python/client).

### 3. Check your credits

`account()` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```python
from datetime import timedelta

account = client.account()
print(account.email, account.organization.name, account.scopes)
quota = account.lookup_quota
print(quota.credits, "credits, resetting in", timedelta(seconds=quota.resets_in))
```

### 4. Handle errors

Every exception class the SDK defines derives from `SynthientError`. A request that fails with a non-success HTTP status raises an `APIError`:

```python
try:
    client.lookup_ip("8.8.8.8")
except synthient.APIError as error:
    if error.status_code == 402:
        print("out of lookup credits")
    elif error.status_code == 429 and error.retry_after is not None:
        print("rate limited, retry after", error.retry_after)
    elif error.status_code == 429:
        print("monthly request budget spent")
    else:
        print("request", error.request_id, "failed:", error.detail or error.title)
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/python/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/python/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/python/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/python/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/python/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/python/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.