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

__init__

  • __init__(token, *, api_url, api_public_url, max_retries, min_delay_between_retries, timeout_short, timeout_medium, timeout_long, timeout_max, headers, user_agent_suffix, 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. The /v2 API version segment is appended unless the URL path already ends with it.

    • 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. The /v2 API version segment is appended unless the URL path already ends with it.

    • optionalkeyword-onlymax_retries: int = DEFAULT_MAX_RETRIES

      How many times to retry a failed request at most. Set to 0 to disable retries.

    • 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-onlyuser_agent_suffix: (str | list[str]) | None = None

      Extra part or parts appended to the default User-Agent header, separated by ; , for example to identify the tool built on top of the client. With with_custom_http_client, pass it to the HTTP client's constructor.

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

      Compression algorithm for request bodies. Defaults to 'gzip'. Pass a string literal to select an algorithm, or an HttpCompressor instance for finer-grained control. 'brotli' needs the brotli extra (pip install "apify-client[brotli]"). It is not the default because the brotli package is a C extension, while gzip support is part of the Python standard library. 'zstd' uses the standard library on Python 3.14 and newer when the Python build includes zstd, and needs the zstd extra (pip install "apify-client[zstd]") before that.

    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

    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).

stats

Statistics about API client usage and rate limit errors.

These are the statistics of the HTTP client in use. A custom HTTP client that overrides call counts only what its own implementation records.

token

token: str | None

The Apify API token used by the client.