Skip to main content
Version: Next

ApifyClient

Synchronous client for the Apify API.

This is the main entry point for interacting with the Apify platform. 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

from apify_client import ApifyClient

client = ApifyClient(token='MY-APIFY-TOKEN')

# Start an Actor and wait for it to finish.
actor_client = client.actor('apify/python-example')
run = 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 = dataset_client.list_items().items
    for item in items:
        print(item)

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 ActorClient

actors

  • Get the sub-client for the Actor collection, allowing to list and create Actors.

    Returns ActorCollectionClient

build

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

    Parameters

    • build_id: str

      ID of the Actor build to be manipulated.

    Returns BuildClient

builds

dataset

  • Get the sub-client for a specific dataset.

    Parameters

    • dataset_id: str

      ID of the dataset to be manipulated.

    Returns DatasetClient

datasets

  • Get the sub-client for the dataset collection, allowing to list and create datasets.

    Returns DatasetCollectionClient

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 KeyValueStoreClient

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 LogClient

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 RequestQueueClient

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 RunClient

runs

  • Get the sub-client for the run collection, allowing to list Actor runs.

    Returns RunCollectionClient

schedule

  • Get the sub-client for a specific schedule.

    Parameters

    • schedule_id: str

      ID of the schedule to be manipulated.

    Returns ScheduleClient

schedules

store

  • Get the sub-client for the Apify Store, allowing to list Actors published in the store.

    Returns StoreCollectionClient

task

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

    Parameters

    • task_id: str

      ID of the task to be manipulated.

    Returns TaskClient

tasks

  • Get the sub-client for the task collection, allowing to list and create Actor tasks.

    Returns TaskCollectionClient

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 UserClient

webhook

  • Get the sub-client for a specific webhook.

    Parameters

    • webhook_id: str

      ID of the webhook to be manipulated.

    Returns WebhookClient

webhook_dispatch

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

    Parameters

    • webhook_dispatch_id: str

      ID of the webhook dispatch to access.

    Returns WebhookDispatchClient

webhook_dispatches

webhooks

  • Get the sub-client for the webhook collection, allowing to list and create webhooks.

    Returns WebhookCollectionClient

with_custom_http_client

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

  • Create an ApifyClient 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 HttpClient pipeline handles request preparation, retries, timeouts, and API errors unless overridden.

    Usage

    from apify_client import ApifyClient
    from apify_client.http_clients import HttpClient, HttpResponse


    class MyHttpClient(HttpClient):
        def send_request(self, *, method, url, headers, content, timeout, stream) -> HttpResponse:
            ...


    client = ApifyClient.with_custom_http_client(
        token='MY-APIFY-TOKEN',
        http_client=MyHttpClient(),
    )

    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: HttpClient

      A custom HTTP client instance extending HttpClient.

    Returns ApifyClient

Properties

http_client

http_client: HttpClient

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 ImpitHttpClient otherwise (lazily created on first access).

token

token: str | None

The Apify API token used by the client.

Page Options