Skip to main content
Version: Next

ApifyClientAsync

Asynchronous client for the Apify API.

This is the main entry point for interacting with the Apify platform using async/await. It provides methods to access resource-specific sub-clients for managing Actors, runs, datasets, key-value stores, request queues, schedules, webhooks, and more.

The client automatically handles retries with exponential backoff for failed or rate-limited requests.

Usage

import asyncio

from apify_client import ApifyClientAsync


async def main() -> None:
    client = ApifyClientAsync(token='MY-APIFY-TOKEN')

    # Start an Actor and wait for it to finish.
    actor_client = client.actor('apify/python-example')
    run = await actor_client.call(run_input={'first_number': 1, 'second_number': 2})

    # Fetch results from the run's default dataset.
    if run is not None:
        dataset_client = client.dataset(run.default_dataset_id)
        items = (await dataset_client.list_items()).items
        for item in items:
            print(item)


asyncio.run(main())

Index

Methods

Properties

Methods

__init__

  • __init__(token, *, api_url, api_public_url, max_retries, min_delay_between_retries, timeout_short, timeout_medium, timeout_long, timeout_max, headers, compression): None

  • Initialize the Apify API client.

    To use a custom HTTP client, use the with_custom_http_client class method instead.

    Parameters

    • optionaltoken: str | None = None

      The Apify API token. You can find your token on the Integrations page in the Apify Console.

    • optionalkeyword-onlyapi_url: str = DEFAULT_API_URL

      The URL of the Apify API server to connect to. Defaults to https://api.apify.com. It can be an internal URL that is not globally accessible, in which case api_public_url should be set as well.

    • optionalkeyword-onlyapi_public_url: str | None = DEFAULT_API_URL

      The globally accessible URL of the Apify API server. Should be set only if api_url is an internal URL that is not globally accessible. Defaults to https://api.apify.com.

    • optionalkeyword-onlymax_retries: int = DEFAULT_MAX_RETRIES

      How many times to retry a failed request at most.

    • optionalkeyword-onlymin_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES

      How long will the client wait between retrying requests (increases exponentially from this value).

    • 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-onlyheaders: dict[str, str] | None = None

      Additional HTTP headers to include in all API requests.

    • optionalkeyword-onlycompression: HttpCompressionAlgorithm | HttpCompressor = 'gzip'

      Compression algorithm for request bodies. Pass a string literal to select an algorithm, or an HttpCompressor instance for finer-grained control.

    Returns None

actor

  • Get the sub-client for a specific Actor.

    Parameters

    • actor_id: str

      ID of the Actor to be manipulated.

    Returns ActorClientAsync

actors

build

  • Get the sub-client for a specific Actor build.

    Parameters

    • build_id: str

      ID of the Actor build to be manipulated.

    Returns BuildClientAsync

builds

dataset

  • Get the sub-client for a specific dataset.

    Parameters

    • dataset_id: str

      ID of the dataset to be manipulated.

    Returns DatasetClientAsync

datasets

key_value_store

  • Get the sub-client for a specific key-value store.

    Parameters

    • key_value_store_id: str

      ID of the key-value store to be manipulated.

    Returns KeyValueStoreClientAsync

key_value_stores

log

  • Get the sub-client for retrieving logs of an Actor build or run.

    Parameters

    • build_or_run_id: str

      ID of the Actor build or run for which to access the log.

    Returns LogClientAsync

request_queue

  • Get the sub-client for a specific request queue.

    Parameters

    • request_queue_id: str

      ID of the request queue to be manipulated.

    • optionalkeyword-onlyclient_key: str | None = None

      A unique identifier of the client accessing the request queue.

    Returns RequestQueueClientAsync

request_queues

run

  • Get the sub-client for a specific Actor run.

    Parameters

    • run_id: str

      ID of the Actor run to be manipulated.

    Returns RunClientAsync

runs

schedule

  • Get the sub-client for a specific schedule.

    Parameters

    • schedule_id: str

      ID of the schedule to be manipulated.

    Returns ScheduleClientAsync

schedules

store

task

  • Get the sub-client for a specific Actor task.

    Parameters

    • task_id: str

      ID of the task to be manipulated.

    Returns TaskClientAsync

tasks

user

  • Get the sub-client for querying user data.

    Parameters

    • optionaluser_id: str | None = None

      ID of user to be queried. If None, queries the user belonging to the token supplied to the client.

    Returns UserClientAsync

webhook

  • Get the sub-client for a specific webhook.

    Parameters

    • webhook_id: str

      ID of the webhook to be manipulated.

    Returns WebhookClientAsync

webhook_dispatch

  • Get the sub-client for a specific webhook dispatch.

    Parameters

    • webhook_dispatch_id: str

      ID of the webhook dispatch to access.

    Returns WebhookDispatchClientAsync

webhook_dispatches

webhooks

with_custom_http_client

  • with_custom_http_client(token, *, api_url, api_public_url, http_client): ApifyClientAsync

  • Create an ApifyClientAsync instance with a custom HTTP client.

    Use this alternative constructor when you want to provide your own HTTP client implementation instead of the default one. The custom client controls its transport configuration; the shared HttpClientAsync pipeline handles request preparation, retries, timeouts, and API errors unless overridden.

    Usage

    from apify_client import ApifyClientAsync
    from apify_client.http_clients import HttpClientAsync, HttpResponse


    class MyHttpClientAsync(HttpClientAsync):
        async def send_request(self, *, method, url, headers, content, timeout, stream) -> HttpResponse:
            ...


    client = ApifyClientAsync.with_custom_http_client(
        token='MY-APIFY-TOKEN',
        http_client=MyHttpClientAsync(),
    )

    Parameters

    • optionaltoken: str | None = None

      The Apify API token. It is set as the Authorization header on the custom client, unless the client already has one configured.

    • optionalkeyword-onlyapi_url: str = DEFAULT_API_URL

      The URL of the Apify API server to connect to. Defaults to https://api.apify.com.

    • optionalkeyword-onlyapi_public_url: str | None = DEFAULT_API_URL

      The globally accessible URL of the Apify API server. Defaults to https://api.apify.com.

    • keyword-onlyhttp_client: HttpClientAsync

      A custom HTTP client instance extending HttpClientAsync.

    Returns ApifyClientAsync

Properties

http_client

http_client: HttpClientAsync

The HTTP client instance used for API communication.

Returns the custom HTTP client if one was provided via with_custom_http_client, or the default ImpitHttpClientAsync otherwise (lazily created on first access).

token

token: str | None

The Apify API token used by the client.

Page Options