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
```