Skip to main content
Version: Next

Httpx2HttpClientAsync

Asynchronous HTTP client for the Apify API built on top of HTTPX2.

This client wraps httpx2.AsyncClient and adds automatic retries with exponential backoff for rate-limited (HTTP 429) and server error (HTTP 5xx) responses.

HTTPX2 applies a request timeout to each socket operation rather than to the request as a whole, so a response whose body arrives slowly keeps resetting it and can outlast both the requested timeout and timeout_max. The default Impit client enforces the same value as a deadline for the whole request, body included.

Requires the httpx2 extra: pip install "apify-client[httpx2]". The httpx2 package is Pydantic's maintained continuation of HTTPX.

Hierarchy

Index

Methods

Methods

__aenter__

  • async __aenter__(): Self

__aexit__

  • async __aexit__(exc_type, exc_value, traceback): None

  • Close resources owned by the asynchronous HTTP client.

    Parameters

    • exc_type: type[BaseException] | None
    • exc_value: BaseException | None
    • traceback: TracebackType | None

    Returns None

__init__

  • __init__(*, token, timeout_short, timeout_medium, timeout_long, timeout_max, max_retries, min_delay_between_retries, statistics, headers, user_agent_suffix, http_compressor): None

  • Initialize the HTTPX2-based asynchronous HTTP client.

    Parameters

    • optionalkeyword-onlytoken: str | None = None

      Apify API token for authentication.

    • optionalkeyword-onlytimeout_short: timedelta = DEFAULT_TIMEOUT_SHORT

      Default timeout for short-duration API operations (simple CRUD operations, ...).

    • optionalkeyword-onlytimeout_medium: timedelta = DEFAULT_TIMEOUT_MEDIUM

      Default timeout for medium-duration API operations (batch operations, listing, ...).

    • optionalkeyword-onlytimeout_long: timedelta = DEFAULT_TIMEOUT_LONG

      Default timeout for long-duration API operations (long-polling, streaming, ...).

    • optionalkeyword-onlytimeout_max: timedelta = DEFAULT_TIMEOUT_MAX

      Maximum timeout cap for any single request attempt, including tier and per-call timeouts.

    • optionalkeyword-onlymax_retries: int = DEFAULT_MAX_RETRIES

      Maximum number of retry attempts for failed requests. Set to 0 to disable retries.

    • optionalkeyword-onlymin_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES

      Minimum delay between retries (increases exponentially with each attempt).

    • optionalkeyword-onlystatistics: ClientStatistics | None = None

      Statistics tracker for API calls. Created automatically if not provided.

    • optionalkeyword-onlyheaders: dict[str, str] | None = None

      Additional HTTP headers to include in all requests.

    • optionalkeyword-onlyuser_agent_suffix: (str | list[str]) | None = None

      Extra part or parts appended to the default User-Agent header, separated by ; .

    • optionalkeyword-onlyhttp_compressor: HttpCompressor | None = None

      Compressor used to compress request bodies. Defaults to GzipHttpCompressor.

    Returns None

aclose

  • async aclose(): None

call

  • async call(*, method, url, headers, params, data, json, stream, timeout, compression, authorization_header, raise_for_status, retry_status_codes, retry_transport_errors, follow_redirects): HttpResponse

  • Make an HTTP request with automatic retry and exponential backoff.

    Parameters

    • keyword-onlymethod: str

      HTTP method (GET, POST, PUT, DELETE, etc.).

    • keyword-onlyurl: str

      Full URL to make the request to.

    • optionalkeyword-onlyheaders: dict[str, str] | None = None

      Additional headers to include.

    • optionalkeyword-onlyparams: QueryParams | None = None

      Query parameters to append to the URL. See QueryParamValue for how each value is converted before it is sent.

    • optionalkeyword-onlydata: str | bytes | bytearray | StreamedBodySource | None = None

      Raw request body. An io.IOBase stream such as an open file, an iterable of byte chunks, or a streamed HttpResponse is sent in chunks as it is read, and any other object with a callable read is read whole, see StreamedRequestBody. Streaming is experimental, and its behavior may change in future versions. Cannot be used together with json.

    • optionalkeyword-onlyjson: JsonSerializable | None = None

      JSON-serializable data for the request body. Cannot be used together with data.

    • optionalkeyword-onlystream: bool | None = None

      Whether to stream the response body.

    • optionalkeyword-onlytimeout: Timeout = 'medium'

      Timeout for the API HTTP request. Use short, medium, or long tier literals for preconfigured timeouts. A timedelta overrides it for this call (capped at timeout_max), and no_timeout disables the timeout entirely.

    • optionalkeyword-onlycompression: HttpCompressor | bool = True

      How to compress the request body. True uses the client's compressor, an HttpCompressor is used for this request only, and False sends the body uncompressed.

    • optionalkeyword-onlyauthorization_header: AuthorizationHeader = 'Authorization'

      Header that carries the client's API token for this request, see AuthorizationHeader. A per-request header of either name still wins.

    • optionalkeyword-onlyraise_for_status: bool = True

      Whether an error status raises ApifyApiError. With False, the error response is returned once no retry follows, and a rate limit (429) doesn't count toward the client's statistics, which track the API's rate limits.

    • optionalkeyword-onlyretry_status_codes: Collection[int] | None = None

      Status codes to retry. Defaults to rate limits (429) and server errors (5xx).

    • optionalkeyword-onlyretry_transport_errors: bool = True

      Whether transport errors, timeouts included, are retried. With False, the first one is raised, since the request may have reached the server before it failed.

    • optionalkeyword-onlyfollow_redirects: bool = True

      Whether the transport follows redirects. With False, a redirect response is handled like an error status, so headers that carry the token never go to a host the server picked.

    Returns HttpResponse

    The HTTP response object.

is_retryable_transport_error

  • is_retryable_transport_error(exc): bool

  • Return whether an underlying HTTP-library exception is retryable.

    The default classifies nothing as retryable, so a transport that doesn't override it gives up on the first connection failure. Every transport adapter should map its own transient error types here.

    Parameters

    • exc: Exception

    Returns bool

is_timeout_error

  • is_timeout_error(exc): bool

  • Return whether an exception represents a transport timeout.

    Recognizes Python's own TimeoutError. Transport adapters extend it with the timeout types their HTTP library defines.

    Parameters

    • exc: Exception

    Returns bool

send_request

  • async send_request(*, method, url, headers, content, timeout, stream, follow_redirects): HttpResponse

  • Send one request through the underlying HTTP library.

    Required by the inherited call, so a transport adapter must implement it. Overriding call itself bypasses it entirely. Let the HTTP library's exceptions propagate unwrapped: call classifies them through is_retryable_transport_error and is_timeout_error.

    Parameters

    • keyword-onlymethod: str

      HTTP method (GET, POST, PUT, DELETE, etc.).

    • keyword-onlyurl: str

      Full request URL, with the query parameters already encoded into it.

    • keyword-onlyheaders: dict[str, str]

      Final request headers, with the client's default headers already merged in.

    • keyword-onlycontent: (bytes | AsyncIterator[bytes]) | None

      Request body, already serialized and compressed, an iterator of chunks for a streamed body (an async iterator in the asynchronous client), or None for a request without a body.

    • keyword-onlytimeout: float | None

      Timeout for this attempt in seconds, or None for no timeout at all.

    • keyword-onlystream: bool

      Whether to return the response with the body unread, so the caller can stream it.

    • optionalkeyword-onlyfollow_redirects: bool = True

      Whether to follow redirects. With False, return a redirect response as it is. call passes this argument only as False, for a request whose headers carry a token that must not follow a redirect to another host, so a transport that doesn't accept it fails such a request.

    Returns HttpResponse

    The HTTP response object.

set_default_authorization

  • set_default_authorization(token): None

  • Set the Authorization header from the token, unless an authorization header is already configured.

    Parameters

    • token: str

      The Apify API token to set as the Bearer authorization.

    Returns None

Page Options