API Reference

This page documents the public surface of the tierproxy package. All symbols listed here are stable and follow semantic versioning; anything inside tierproxy._internal or modules prefixed with _ is private and may change between releases.

Client

class tierproxy.TierProxy(api_key=None, *, base_url='https://gw.tierproxy.com:8444', timeout=30.0, http_timeout=30.0, max_retries=3, retry_policy=None, http_client=None, user_agent_suffix=None, routing=None, monthly_budget_usd=None, cache_ttl=0.0, cache_max_size=256, cache_max_response_size=262144, auto_failover=False, auto_failover_max_attempts=3)

Bases: object

Sync client for the tierproxy public REST API.

Parameters:

• api_key (str | None)

• base_url (str)

• timeout (float)

• http_timeout (float)

• max_retries (int)

• retry_policy (RetryPolicy | None)

• http_client (httpx.Client | None)

• user_agent_suffix (str | None)

• routing (str | None)

• monthly_budget_usd (float | None)

• cache_ttl (float)

• cache_max_size (int)

• cache_max_response_size (int)

• auto_failover (bool)

• auto_failover_max_attempts (int)

cost_for(resp)

Return USD cost for a response. Lazy 30s-cached fetch under the hood.

Parameters:

resp (Response)

Return type:

float | None

upstream_for(resp)

Return upstream_id that served a response. Lazy 30s-cached fetch.

Parameters:

resp (Response)

Return type:

str | None

request(method, url, **kwargs)

Make an HTTP request through the tierproxy gateway.

Targeting kwargs (country, session_id, …) are split out; everything else forwards to httpx (timeout, json, data, headers, params, …).

When stream=True is passed, returns a context manager yielding an httpx.Response whose body must be iterated (iter_bytes/iter_text). Cache, failover, and cookie persistence are skipped in stream mode.

Parameters:

• method (str)

• url (str)

• kwargs (Any)

Return type:

Any

session(**targeting_kwargs)

Return an httpx.Client preconfigured with targeting baked in.

Useful when the caller wants to make many requests with the same targeting (e.g. one scraper job) without rebuilding the proxy every call.

Parameters:

targeting_kwargs (Any)

Return type:

Client

target(**kwargs)

Builder pattern: g.target(country=’US’).get(’https://x.com’).

Parameters:

kwargs (Any)

Return type:

TargetedRequest

class tierproxy.AsyncTierProxy(api_key=None, *, base_url='https://gw.tierproxy.com:8444', timeout=30.0, http_timeout=30.0, max_retries=3, retry_policy=None, http_client=None, user_agent_suffix=None, routing=None, monthly_budget_usd=None, cache_ttl=0.0, cache_max_size=256, cache_max_response_size=262144, auto_failover=False, auto_failover_max_attempts=3)

Bases: object

Parameters:

• api_key (str | None)

• base_url (str)

• timeout (float)

• http_timeout (float)

• max_retries (int)

• retry_policy (RetryPolicy | None)

• http_client (httpx.AsyncClient | None)

• user_agent_suffix (str | None)

• routing (str | None)

• monthly_budget_usd (float | None)

• cache_ttl (float)

• cache_max_size (int)

• cache_max_response_size (int)

• auto_failover (bool)

• auto_failover_max_attempts (int)

async request(method, url, **kwargs)

Async request. With stream=True, returns an async context manager yielding an httpx.Response for streaming.

Parameters:

• method (str)

• url (str)

• kwargs (Any)

Return type:

Any

Resources

class tierproxy.resources.me.Me(*, client_id, plan_id, status, quota_bytes_month, used_bytes_month, allowed_upstreams, rate_per_sec=0, bytes_per_sec=0)

Bases: BaseModel

Parameters:

• client_id (str)

• plan_id (str)

• status (str)

• quota_bytes_month (int)

• used_bytes_month (int)

• allowed_upstreams (list[str])

• rate_per_sec (float)

• bytes_per_sec (float)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tierproxy.resources.usage.UsageDay(*, date, bytes_up, bytes_down, cost_usd)

Bases: BaseModel

Parameters:

• date (str)

• bytes_up (int)

• bytes_down (int)

• cost_usd (float)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tierproxy.resources.usage.Usage(*, client_id, from_='', to, days, total_bytes, total_cost_usd)

Bases: BaseModel

Parameters:

• client_id (str)

• from_ (str)

• to (str)

• days (list[UsageDay])

• total_bytes (int)

• total_cost_usd (float)

model_config = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tierproxy.resources.usage.UsageDelta(*, ts, total_bytes, delta_bytes)

Bases: BaseModel

Parameters:

• ts (str)

• total_bytes (int)

• delta_bytes (int)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tierproxy.resources.health.UpstreamHealth(*, upstream_id, state, cb_state, success_rate, latency_p95_ms, cost_per_gb_usd)

Bases: BaseModel

Parameters:

• upstream_id (str)

• state (str)

• cb_state (str)

• success_rate (float)

• latency_p95_ms (int)

• cost_per_gb_usd (float)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Proxy URL builder & selector

ProxyURL builder. Two modes: - header_mode (default): caller emits X-Proxy-Geo etc headers; useful in httpx/requests - username_encoding: encodes modifiers as customer-X-cc-US-…; useful for Playwright

class tierproxy.proxy.url_builder.ProxyURL(api_key: 'str', password: 'str' = '', pool: 'Pool | None' = None, country: 'str | None' = None, city: 'str | None' = None, session_id: 'str | None' = None, session_duration_minutes: 'int | None' = None, upstream_hint: 'str | None' = None, host: 'str' = 'gw.tierproxy.com', port_https: 'int' = 443, port_socks5: 'int' = 1080, mode: 'Mode' = 'headers')

Bases: object

Parameters:

• api_key (str)

• password (str)

• pool (Literal['residential', 'datacenter', 'isp', 'mobile'] | None)

• country (str | None)

• city (str | None)

• session_id (str | None)

• session_duration_minutes (int | None)

• upstream_hint (str | None)

• host (str)

• port_https (int)

• port_socks5 (int)

• mode (Literal['headers', 'username_encoding'])

encoded_username()

Build username with all modifiers inline (Smartproxy-style).

Return type:

str

headers()

Headers form. Set on every request. Gateway parses these.

Return type:

dict[str, str]

http_url()

http://user:pass@host:port for HTTP proxy clients.

Return type:

str

Client-side smart selector. Reads /v1/health/upstreams + picks one based on cost / latency / success-rate, then emits an upstream-hint.

tierproxy.proxy.selector.pick(upstreams, strategy='balanced')

Pick the best upstream by strategy. Excludes red/open ones.

‘balanced’ = weighted score (success_rate / cost / latency).

Parameters:

• upstreams (list[UpstreamHealth])

• strategy (Strategy)

Return type:

UpstreamHealth

tierproxy.proxy.selector.pick_next(upstreams, exclude, strategy='balanced')

Pick the best upstream excluding tried IDs. Returns None if exhausted.

Parameters:

• upstreams (list[UpstreamHealth])

• exclude (set[str])

• strategy (Strategy)

Return type:

UpstreamHealth | None

class tierproxy.proxy.selector.SmartSelector(client, strategy='balanced', cache_ttl=30.0)

Bases: object

Convenience: keeps a cached health snapshot, refreshes every N seconds.

Parameters:

• client (TierProxy)

• strategy (Strategy)

• cache_ttl (float)

Retry policy

class tierproxy.retry.RetryPolicy(max_retries: 'int' = 3, initial_delay_seconds: 'float' = 0.5, max_delay_seconds: 'float' = 30.0, multiplier: 'float' = 2.0, jitter: 'float' = 0.25, retry_on_status: 'frozenset[int]' = <factory>, retry_on_methods: 'frozenset[str]' = <factory>)

Bases: object

Parameters:

• max_retries (int)

• initial_delay_seconds (float)

• max_delay_seconds (float)

• multiplier (float)

• jitter (float)

• retry_on_status (frozenset[int])

• retry_on_methods (frozenset[str])

Exceptions

Public exception hierarchy. Every exception carries request_id for support.

exception tierproxy.errors.TierProxyError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: Exception

Base class. Catch this to handle any SDK error.

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.AuthenticationError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.PermissionError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.NotFoundError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.ValidationError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.ConflictError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.RateLimitError(*args, retry_after=None, **kwargs)

Bases: TierProxyError

Parameters:

• args (Any)

• retry_after (int | None)

• kwargs (Any)

Return type:

None

exception tierproxy.errors.ServerError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.TimeoutError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

exception tierproxy.errors.ConnectionError(message, *, status_code=None, request_id=None, error_type=None, problem=None)

Bases: TierProxyError

Parameters:

• message (str)

• status_code (int | None)

• request_id (str | None)

• error_type (str | None)

• problem (dict[str, Any] | None)

Return type:

None

tierproxy.errors.from_problem(status_code, problem)

Map an RFC 7807 problem+json body to the right exception.

Parameters:

• status_code (int)

• problem (dict[str, Any])

Return type:

TierProxyError