0
# Apify Client
1
2
A comprehensive Python client library for the Apify web scraping and automation platform. Provides convenient access to all Apify API resources including Actors, datasets, key-value stores, request queues, and platform management, with both synchronous and asynchronous support.
3
4
## Package Information
5
6
- **Package Name**: apify-client
7
- **Language**: Python
8
- **Installation**: `pip install apify-client`
9
- **Requires**: Python ≥ 3.10
10
11
## Core Imports
12
13
```python
14
from apify_client import ApifyClient
15
```
16
17
For asynchronous operations:
18
19
```python
20
from apify_client import ApifyClientAsync
21
```
22
23
## Basic Usage
24
25
```python
26
from apify_client import ApifyClient
27
28
# Initialize client with API token
29
client = ApifyClient('your-api-token')
30
31
# Run an Actor and get results
32
run = client.actor('john-doe/web-scraper').call(run_input={'startUrls': ['https://example.com']})
33
34
# Access the default dataset
35
dataset = client.dataset(run['defaultDatasetId'])
36
items = dataset.list_items()
37
38
print(f"Scraped {items.count} items")
39
for item in items.items:
40
print(item)
41
42
# Store data in key-value store
43
kvs = client.key_value_stores().get_or_create(name='my-storage')
44
client.key_value_store(kvs['id']).set_record('results', {'status': 'completed', 'itemCount': items.count})
45
```
46
47
## Architecture
48
49
The Apify Client follows a hierarchical resource-based architecture:
50
51
- **Client Classes**: Main entry points (`ApifyClient`, `ApifyClientAsync`) managing authentication and base configuration
52
- **Resource Clients**: Individual resource managers (e.g., `ActorClient`, `DatasetClient`) for specific platform resources
53
- **Collection Clients**: Managers for resource collections (e.g., `ActorCollectionClient`) providing listing and creation capabilities
54
- **Specialized Clients**: Task-specific clients like `LogClient` for streaming logs and `RequestQueueClient` for queue operations
55
56
All operations support both synchronous and asynchronous execution patterns, with consistent method signatures and error handling across the entire API surface.
57
58
## Capabilities
59
60
### Client Initialization
61
62
Main client classes for accessing the Apify API with authentication and configuration options.
63
64
```python { .api }
65
class ApifyClient:
66
def __init__(
67
self,
68
token: str | None = None,
69
*,
70
api_url: str | None = None,
71
max_retries: int | None = 8,
72
min_delay_between_retries_millis: int | None = 500,
73
timeout_secs: int | None = 360,
74
) -> None: ...
75
76
class ApifyClientAsync:
77
def __init__(
78
self,
79
token: str | None = None,
80
*,
81
api_url: str | None = None,
82
max_retries: int | None = 8,
83
min_delay_between_retries_millis: int | None = 500,
84
timeout_secs: int | None = 360,
85
) -> None: ...
86
```
87
88
### Actor Management
89
90
Comprehensive Actor lifecycle management including creation, configuration, execution, builds, versions, and environment variables.
91
92
```python { .api }
93
def actor(self, actor_id: str) -> ActorClient: ...
94
def actors(self) -> ActorCollectionClient: ...
95
```
96
97
[Actor Management](./actors.md)
98
99
### Data Storage
100
101
Access to Apify's data storage systems including datasets for structured data and key-value stores for arbitrary data storage.
102
103
```python { .api }
104
def dataset(self, dataset_id: str) -> DatasetClient: ...
105
def datasets(self) -> DatasetCollectionClient: ...
106
def key_value_store(self, key_value_store_id: str) -> KeyValueStoreClient: ...
107
def key_value_stores(self) -> KeyValueStoreCollectionClient: ...
108
```
109
110
[Data Storage](./storage.md)
111
112
### Request Queue Management
113
114
Request queue operations for managing crawling workflows and Actor communication.
115
116
```python { .api }
117
def request_queue(self, request_queue_id: str, *, client_key: str | None = None) -> RequestQueueClient: ...
118
def request_queues(self) -> RequestQueueCollectionClient: ...
119
```
120
121
[Request Queues](./request-queues.md)
122
123
### Run Management
124
125
Actor run lifecycle management including execution monitoring, result access, and advanced operations.
126
127
```python { .api }
128
def run(self, run_id: str) -> RunClient: ...
129
def runs(self) -> RunCollectionClient: ...
130
```
131
132
[Run Management](./runs.md)
133
134
### Build Management
135
136
Actor build operations including triggering builds, monitoring progress, and accessing build artifacts.
137
138
```python { .api }
139
def build(self, build_id: str) -> BuildClient: ...
140
def builds(self) -> BuildCollectionClient: ...
141
```
142
143
[Build Management](./builds.md)
144
145
### Task Management
146
147
Task creation and management for reusable Actor configurations and scheduled executions.
148
149
```python { .api }
150
def task(self, task_id: str) -> TaskClient: ...
151
def tasks(self) -> TaskCollectionClient: ...
152
```
153
154
[Task Management](./tasks.md)
155
156
### Scheduling
157
158
Schedule management for automated Actor and task executions with cron-like functionality.
159
160
```python { .api }
161
def schedule(self, schedule_id: str) -> ScheduleClient: ...
162
def schedules(self) -> ScheduleCollectionClient: ...
163
```
164
165
[Scheduling](./schedules.md)
166
167
### Webhooks
168
169
Webhook configuration and management for real-time notifications and integrations.
170
171
```python { .api }
172
def webhook(self, webhook_id: str) -> WebhookClient: ...
173
def webhooks(self) -> WebhookCollectionClient: ...
174
def webhook_dispatch(self, webhook_dispatch_id: str) -> WebhookDispatchClient: ...
175
def webhook_dispatches(self) -> WebhookDispatchCollectionClient: ...
176
```
177
178
[Webhooks](./webhooks.md)
179
180
### User Management
181
182
User account information, usage monitoring, and account limit management.
183
184
```python { .api }
185
def user(self, user_id: str | None = None) -> UserClient: ...
186
```
187
188
[User Management](./users.md)
189
190
### Logging
191
192
Log access and streaming for Actor runs and builds with real-time monitoring capabilities.
193
194
```python { .api }
195
def log(self, build_or_run_id: str) -> LogClient: ...
196
```
197
198
[Logging](./logging.md)
199
200
### Store Integration
201
202
Access to the Apify Store for discovering and using public Actors.
203
204
```python { .api }
205
def store(self) -> StoreCollectionClient: ...
206
```
207
208
[Store Integration](./store.md)
209
210
## Types
211
212
```python { .api }
213
from typing import Any, Generic, TypeVar
214
215
JSONSerializable = str | int | float | bool | None | dict[str, Any] | list[Any]
216
217
T = TypeVar('T')
218
219
class ListPage(Generic[T]):
220
"""A single page of items returned from a list() method."""
221
222
items: list[T]
223
"""List of returned objects on this page."""
224
225
count: int
226
"""Count of the returned objects on this page."""
227
228
offset: int
229
"""The limit on the number of returned objects offset specified in the API call."""
230
231
limit: int
232
"""The offset of the first object specified in the API call"""
233
234
total: int
235
"""Total number of objects matching the API call criteria."""
236
237
desc: bool
238
"""Whether the listing is descending or not."""
239
240
def __init__(self, data: dict) -> None: ...
241
242
# External types from apify_shared package
243
from apify_shared.consts import (
244
StorageGeneralAccess, # Enum for storage access levels
245
ActorJobStatus, # Enum for Actor job statuses
246
MetaOrigin, # Enum for run origins
247
ActorSourceType, # Enum for Actor source types
248
WebhookEventType, # Enum for webhook event types
249
RunGeneralAccess # Enum for run access levels
250
)
251
```
252
253
## Error Handling
254
255
```python { .api }
256
class ApifyClientError(Exception):
257
"""Base class for errors specific to the Apify API Client."""
258
259
class ApifyApiError(ApifyClientError):
260
"""Error specific to requests to the Apify API."""
261
262
def __init__(self, response, attempt: int, method: str = 'GET') -> None: ...
263
264
message: str | None
265
type: str | None
266
data: dict[str, str]
267
name: str
268
status_code: int
269
attempt: int
270
http_method: str
271
272
class InvalidResponseBodyError(ApifyClientError):
273
"""Error caused by the response body failing to be parsed."""
274
275
def __init__(self, response) -> None: ...
276
277
name: str
278
code: str
279
response: Any
280
```
281
282
## Constants
283
284
```python { .api }
285
DEFAULT_API_URL: str = 'https://api.apify.com'
286
DEFAULT_TIMEOUT: int = 360 # seconds
287
API_VERSION: str = 'v2'
288
__version__: str # Package version
289
```