Apify API client for Python

The official Python client for the Apify REST API.

apify-client lets you talk to the Apify platform from Python — run Actors, manage storages (datasets, key-value stores, request queues), schedule tasks, configure webhooks, and use everything else exposed by the Apify API. It ships both synchronous and asynchronous clients, fully typed responses, automatic retries with exponential backoff, tiered timeouts, pagination helpers, streaming, and a pluggable HTTP layer.

If you want to build Apify Actors in Python rather than consume the API, use the Apify SDK for Python instead — it bundles this client and adds Actor-side primitives.

Table of contents

• Installation
• Quick start
• Features
• Usage examples
• Documentation
• Related projects
• Support and community
• Contributing
• License

Installation

apify-client requires Python 3.11 or higher and is published on PyPI and conda-forge.

• From PyPI, it can be installed for example with pip:

  pip install apify-client
  

  or with uv:

  uv add apify-client
  

  or any other Python package manager that consumes PyPI.

  The client compresses request bodies with gzip by default (no extra dependencies required). To opt in to brotli (better compression ratio), install the optional extra and pass compression='brotli':

  pip install "apify-client[brotli]"
  # or
  uv add "apify-client[brotli]"
  

  Impit is the default HTTP client and is installed automatically. To use the built-in HTTPX2 client instead, install the optional httpx2 extra, which provides Pydantic's maintained continuation of HTTPX, and pass http_client=Httpx2HttpClient() to ApifyClient.with_custom_http_client():

  pip install "apify-client[httpx2]"
  # or
  uv add "apify-client[httpx2]"
  

• From conda-forge, it can be installed with conda:

  conda install conda-forge::apify-client
  

Quick start

You'll need an Apify API token — find yours in the Integrations section of Apify Console. Pass it to the client and you're ready to go.

Synchronous client

from apify_client import ApifyClient

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

# Start an Actor and wait for it to finish.
run = client.actor('apify/hello-world').call(
    run_input={'message': 'Hello, Apify!'},
)
if run is None:
    raise RuntimeError('Actor run was not found.')

# Iterate items from the run's default dataset.
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

Asynchronous client

import asyncio

from apify_client import ApifyClientAsync


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

    run = await client.actor('apify/hello-world').call(
        run_input={'message': 'Hello, Apify!'},
    )
    if run is None:
        raise RuntimeError('Actor run was not found.')

    # Iterate items from the run's default dataset.
    async for item in client.dataset(run.default_dataset_id).iterate_items():
        print(item)


asyncio.run(main())

Keep your token secret. It authorizes requests on your behalf and can incur usage costs. Never commit it to source control or expose it to client-side code.

For a guided walkthrough — authenticating, running an Actor, and reading its results — see the Quick start guide.

Features

• Synchronous and asynchronous clients — pick ApifyClient or ApifyClientAsync to match your codebase; both expose the same API (Asyncio support).
• Fully typed responses — every method returns a Pydantic model generated from the Apify OpenAPI spec, with IDE autocomplete and runtime validation (Typed models).
• Automatic retries — exponential backoff for network errors, HTTP 429, and 5xx responses, configurable per client (Retries).
• Tiered timeouts — short / medium / long tiers picked per endpoint, overridable per call (Timeouts).
• Pagination and streaming — iterate datasets, key-value store keys, or live logs without manual paging or buffering, and upload large records straight from a file or another stream (Pagination, Streaming).
• Convenience methods — call(), wait_for_finish(), nested resource access, and other shortcuts that hide platform quirks (Convenience methods).
• Pluggable HTTP layer — use the default Impit-based client, opt in to the built-in HTTPX2 client, or plug in any custom implementation (HTTP clients).
• Structured errors — every API error surfaces as an ApifyApiError with HTTP-specific subclasses for precise handling (Error handling).
• Debug logging — opt-in structured logging on the apify_client logger captures request URLs, status codes, retry attempts, and more (Logging).

Usage examples

The client mirrors the platform's resource model. Each entry point returns either a single-resource client for an individual item or a collection client for listing and creating items (Single and collection clients).

List Actors and create one

actors = client.actors()
print(actors.list(limit=10).items)

new_actor = actors.create(name='my-actor')

Stream live logs while a run is in progress

run = client.actor('apify/web-scraper').start(run_input={...})

with client.run(run.id).log().stream() as log_stream:
    for chunk in log_stream.iter_bytes():
        print(chunk.decode(), end='')

Read and write key-value store records

store = client.key_value_store('STORE-ID')
store.set_record('greeting', {'message': 'Hello!'})
record = store.get_record('greeting')

Iterate dataset items with automatic pagination

for item in client.dataset('DATASET-ID').iterate_items(fields=['title', 'url']):
    process(item)

Tune retries and timeouts

from datetime import timedelta

from apify_client import ApifyClient

client = ApifyClient(
    token='MY-APIFY-TOKEN',
    max_retries=8,
    min_delay_between_retries=timedelta(milliseconds=500),
    timeout_long=timedelta(minutes=10),
)

For end-to-end recipes — passing input, managing tasks for reusable input, retrieving and merging Actor data, integrating with Pandas, plugging in a custom HTTP client — see the Guides.

Documentation

The full documentation lives at docs.apify.com/api/client/python.

Related projects

• Apify SDK for Python — toolkit for building Apify Actors in Python (this client is bundled with it).
• Crawlee for Python — high-level web scraping and browser automation framework that powers many Actors.
• Apify API client for JavaScript / TypeScript — equivalent Apify API client for Node.js.
• Apify SDK for JavaScript / TypeScript — equivalent Apify SDK for Node.js.
• Crawlee for JavaScript / TypeScript — original Node.js implementation of the Crawlee framework.
• Apify CLI — command-line tool for interacting with the Apify platform: managing Actors, runs, storages, local development, and deployment.

Support and community

• Discord — chat with the team and other users on the Apify Discord server.
• GitHub issues — report a bug or request a feature in the repository's issue tracker.

Contributing

Bug reports, fixes, and improvements are welcome! See CONTRIBUTING.md for the development setup, coding standards, testing, and the release process.

License

Released under the Apache License 2.0.