This release is a pre-release and may not be stable for production use.
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
gzipby default (no extra dependencies required). To opt in tobrotli(better compression ratio), install the optional extra and passcompression='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 HTTPX client instead, install the optional
httpx2extra, which provides Pydantic's maintained continuation of HTTPX, and passhttp_client=Httpx2HttpClient()toApifyClient.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
ApifyClientorApifyClientAsyncto 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 (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 HTTPX client, or plug in any custom implementation (HTTP clients).
- Structured errors — every API error surfaces as an
ApifyApiErrorwith HTTP-specific subclasses for precise handling (Error handling). - Debug logging — opt-in structured logging on the
apify_clientlogger 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.
| Section | What you'll find |
|---|---|
| Introduction | Overview, prerequisites, and a tour of the client. |
| Quick start | Authenticate, run an Actor, and fetch its results step by step. |
| Concepts | Asyncio, single vs. collection clients, nested clients, error handling, retries, logging, convenience methods, pagination, streaming, HTTP clients, timeouts. |
| Guides | Pass input to an Actor, manage tasks for reusable input, retrieve Actor data, integrate with data libraries (e.g. Pandas), build a custom HTTP client. |
| Upgrading | Migrating between major versions. |
| API reference | Generated reference for every class, method, and model. |
| Changelog | Release history and breaking changes. |
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. The repo uses uv for project management and Poe the Poet as a task runner; the typical loop is:
uv run poe install-dev # install dev deps and git hooks
uv run poe check-code # lint, type-check, unit tests, docstring check
License
Released under the Apache License 2.0.
2 maintainers
Release files for apify-client 3.1.4b12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| apify_client-3.1.4b12.tar.gz | 142.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| apify_client-3.1.4b12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:301.6 kB
Release files / apify_client-3.1.4b12.tar.gz
| Download URL | apify_client-3.1.4b12.tar.gz |
|---|---|
| Size | 142.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c2e73c3ad87fd90433dd0cd5a2b95793642f00bce486f555e4d1017ebaa4fd49
|
|
BLAKE2b-256 checksum How to use checksums |
02a4781c7536bb2b977a2e6de55159d538e21ab9caaad304605f13408c789419
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / apify_client-3.1.4b12-py3-none-any.whl
| Download URL | apify_client-3.1.4b12-py3-none-any.whl |
|---|---|
| Size | 158.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
05d65960e2db71b35f697f5ea780f7dc5a8884e8b4c9cbb1a9d8be4ebd53bacc
|
|
BLAKE2b-256 checksum How to use checksums |
5740b4685ba803e8dbbddc59299622beefb13a4b9df2c8a3ef12982ecf290f35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency log
