Client

py3spread.Client

Client(api_key: str | None = None, *, access_token: str | None = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, max_retries: int = 3, transport: BaseTransport | None = None)

Client for the 3spread API.

Takes either a long-lived API key or a short-lived OAuth access token:

Client(api_key="sk_live_...")     # sent as the `apikey` header
Client(access_token="eyJ...")     # sent as `Authorization: Bearer`

With neither, the API key is read from the THREESPREAD_API_KEY environment variable. Get a key at https://3spread.com/auth/signup.

An access token is never read from the environment. OAuth tokens are short-lived, so a token pinned into a process environment would be expired for most of that process's life; the caller is expected to hold a fresh one and build a Client with it. The token is bound at construction, so refreshing means constructing a new Client rather than mutating this one.

Each filing family is an attribute (filings, insiders, institutional_holdings, beneficial_ownership, ...) carrying that family's list/iter/get methods.

request

request(path: str, params: dict[str, Any] | None = None) -> Any

GET a path and return the parsed JSON body, retrying 429/502/503.

health

health() -> dict[str, Any]

Service health, including per-family data_as_of freshness.

health_ready

health_ready() -> dict[str, Any]

Readiness probe.