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.

Getting started

1. Install

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 fetcher is the synthient.grpcschema module, which needs the grpc extra:

pip install 'synthient[grpc]'

2. Make your first lookup

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

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.

3. Check your credits

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

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:

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: create and configure the client, and read the metadata of every API response.
• Lookups: look up IP addresses and domains, and check your account and the API's health.
• Feeds: stream each feed's real-time events and download its hourly and daily Parquet exports.
• Errors and retries: how failed requests are reported, and which requests are retried.
• Types: the fields of every response and event type, and the enumerations they use.
• gRPC schema: fetch the protobuf schema of the Synthient gRPC API.