0
# Actor Management
1

2
Comprehensive Actor lifecycle management including creation, configuration, execution, builds, versions, and environment variables. Actors are the core computational units in the Apify platform.
3

4
## Capabilities
5

6
### Actor Operations
7

8
Individual Actor management operations including retrieval, updates, deletion, execution, and validation.
9

10
```python { .api }
11
from typing import Any, Literal
12
from decimal import Decimal
13
from logging import Logger
14
from apify_shared.consts import ActorJobStatus, MetaOrigin
15
class ActorClient:
16
    def get(self) -> dict | None:
17
        """Retrieve Actor details."""
18
    
19
    def update(
20
        self,
21
        *,
22
        name: str | None = None,
23
        title: str | None = None,
24
        description: str | None = None,
25
        seo_title: str | None = None,
26
        seo_description: str | None = None,
27
        versions: list[dict] | None = None,
28
        restart_on_error: bool | None = None,
29
        is_public: bool | None = None,
30
        is_deprecated: bool | None = None,
31
        is_anonymously_runnable: bool | None = None,
32
        categories: list[str] | None = None,
33
        default_run_build: str | None = None,
34
        default_run_max_items: int | None = None,
35
        default_run_memory_mbytes: int | None = None,
36
        default_run_timeout_secs: int | None = None,
37
        example_run_input_body: Any = None,
38
        example_run_input_content_type: str | None = None,
39
        actor_standby_is_enabled: bool | None = None,
40
        actor_standby_desired_requests_per_actor_run: int | None = None,
41
        actor_standby_max_requests_per_actor_run: int | None = None,
42
        actor_standby_idle_timeout_secs: int | None = None,
43
        actor_standby_build: str | None = None,
44
        actor_standby_memory_mbytes: int | None = None,
45
        pricing_infos: list[dict] | None = None,
46
    ) -> dict:
47
        """Update Actor configuration.
48
        
49
        Args:
50
            name: The name of the Actor
51
            title: The title of the Actor (human-readable)
52
            description: The description for the Actor
53
            seo_title: The title of the Actor optimized for search engines
54
            seo_description: The description of the Actor optimized for search engines
55
            versions: The list of Actor versions
56
            restart_on_error: If true, the main Actor run process will be restarted whenever it exits with non-zero status code
57
            is_public: Whether the Actor is public
58
            is_deprecated: Whether the Actor is deprecated
59
            is_anonymously_runnable: Whether the Actor is anonymously runnable
60
            categories: The categories to which the Actor belongs to
61
            default_run_build: Tag or number of the build to run by default
62
            default_run_max_items: Default limit of results returned by runs (if charged per result)
63
            default_run_memory_mbytes: Default memory allocated for runs in megabytes
64
            default_run_timeout_secs: Default timeout for runs in seconds
65
            example_run_input_body: Input to be prefilled as default for new users
66
            example_run_input_content_type: Content type of the example run input
67
            actor_standby_is_enabled: Whether Actor Standby is enabled
68
            actor_standby_desired_requests_per_actor_run: Desired concurrent HTTP requests per Standby run
69
            actor_standby_max_requests_per_actor_run: Maximum concurrent HTTP requests per Standby run
70
            actor_standby_idle_timeout_secs: Shutdown timeout when Actor receives no requests
71
            actor_standby_build: Build tag or number to run in Standby mode
72
            actor_standby_memory_mbytes: Memory in megabytes for Standby mode
73
            pricing_infos: List of objects describing Actor pricing
74
        """
75
    
76
    def delete(self) -> None:
77
        """Delete the Actor."""
78
    
79
    def start(
80
        self,
81
        *,
82
        run_input: Any = None,
83
        content_type: str | None = None,
84
        build: str | None = None,
85
        max_items: int | None = None,
86
        max_total_charge_usd: Decimal | None = None,
87
        memory_mbytes: int | None = None,
88
        timeout_secs: int | None = None,
89
        wait_for_finish: int | None = None,
90
        webhooks: list[dict] | None = None,
91
    ) -> dict:
92
        """Start Actor run and return immediately.
93
        
94
        Args:
95
            run_input: Input data for the Actor run
96
            content_type: Content type of the run_input
97
            build: Tag or number of the build to run
98
            max_items: Maximum number of results (if charged per result)
99
            max_total_charge_usd: Maximum total charge in USD for the run
100
            memory_mbytes: Memory limit in megabytes
101
            timeout_secs: Timeout in seconds
102
            wait_for_finish: Time to wait for run to finish (in seconds)
103
            webhooks: Webhook configuration list
104
        """
105
    
106
    def call(
107
        self,
108
        *,
109
        run_input: Any = None,
110
        content_type: str | None = None,
111
        build: str | None = None,
112
        max_items: int | None = None,
113
        max_total_charge_usd: Decimal | None = None,
114
        memory_mbytes: int | None = None,
115
        timeout_secs: int | None = None,
116
        webhooks: list[dict] | None = None,
117
        wait_secs: int | None = None,
118
        logger: Logger | None | Literal['default'] = 'default',
119
    ) -> dict | None:
120
        """Start Actor and wait for completion.
121
        
122
        Args:
123
            run_input: Input data for the Actor run
124
            content_type: Content type of the run_input
125
            build: Tag or number of the build to run
126
            max_items: Maximum number of results (if charged per result)
127
            max_total_charge_usd: Maximum total charge in USD for the run
128
            memory_mbytes: Memory limit in megabytes
129
            timeout_secs: Timeout in seconds
130
            webhooks: Webhook configuration list
131
            wait_secs: Maximum time to wait for completion
132
            logger: Logger instance or 'default' for default logger
133
        """
134
    
135
    def build(
136
        self,
137
        *,
138
        version_number: str,
139
        beta_packages: bool | None = None,
140
        tag: str | None = None,
141
        use_cache: bool | None = None,
142
        wait_for_finish: int | None = None,
143
    ) -> dict:
144
        """Build the Actor.
145
        
146
        Args:
147
            version_number: Actor version number to be built (required)
148
            beta_packages: If True, build with beta versions of Apify NPM packages
149
            tag: Tag to be applied to the build on success
150
            use_cache: If true, rebuild using Docker layer cache
151
            wait_for_finish: Maximum seconds to wait for build completion (max 60)
152
        """
153
    
154
    def builds(self) -> BuildCollectionClient:
155
        """Get builds collection client."""
156
    
157
    def runs(self) -> RunCollectionClient:
158
        """Get runs collection client."""
159
    
160
    def default_build(self, **kwargs) -> BuildClient:
161
        """Get default build client."""
162
    
163
    def last_run(self, **kwargs) -> RunClient:
164
        """Get last run client.
165
        
166
        Args:
167
            status (str, optional): Filter by run status
168
            origin (str, optional): Filter by run origin
169
        """
170
    
171
    def versions(self) -> ActorVersionCollectionClient:
172
        """Get versions collection client."""
173
    
174
    def version(self, version_number: str) -> ActorVersionClient:
175
        """Get specific version client."""
176
    
177
    def webhooks(self) -> WebhookCollectionClient:
178
        """Get webhooks collection client."""
179
    
180
    def validate_input(
181
        self, 
182
        run_input: Any = None, 
183
        *, 
184
        build_tag: str | None = None, 
185
        content_type: str | None = None
186
    ) -> bool:
187
        """Validate Actor input against schema.
188
        
189
        Args:
190
            run_input: Input data to validate
191
            build_tag: Tag of the build to validate against
192
            content_type: Content type of the input
193
        """
194

195
class ActorClientAsync:
196
    """Async version of ActorClient with identical methods."""
197
```
198

199
### Actor Collection Operations
200

201
Operations for listing and creating Actors across the platform.
202

203
```python { .api }
204
class ActorCollectionClient:
205
    def list(self, **kwargs) -> ListPage[dict]:
206
        """List Actors.
207
        
208
        Args:
209
            my (bool, optional): Show only user's Actors
210
            limit (int, optional): Maximum number of items
211
            offset (int, optional): Offset for pagination
212
            desc (bool, optional): Sort in descending order
213
            sort_by (str, optional): Field to sort by
214
        """
215
    
216
    def create(self, **kwargs) -> dict:
217
        """Create new Actor.
218
        
219
        Args:
220
            name (str): Actor name
221
            title (str, optional): Display title
222
            description (str, optional): Actor description
223
            versions (list, optional): Initial version configuration
224
            **kwargs: Additional Actor configuration
225
        """
226

227
class ActorCollectionClientAsync:
228
    """Async version of ActorCollectionClient with identical methods."""
229
```
230

231
### Actor Version Management
232

233
Management of Actor versions including source code, environment variables, and configuration.
234

235
```python { .api }
236
class ActorVersionClient:
237
    def get(self) -> dict | None:
238
        """Get Actor version information."""
239
    
240
    def update(self, **kwargs) -> dict:
241
        """Update Actor version.
242
        
243
        Args:
244
            build_tag (str, optional): Build tag
245
            env_vars (list, optional): Environment variables
246
            source_type (str, optional): Source code type
247
            source_files (list, optional): Source files
248
            **kwargs: Additional version configuration
249
        """
250
    
251
    def delete(self) -> None:
252
        """Delete Actor version."""
253
    
254
    def env_vars(self) -> ActorEnvVarCollectionClient:
255
        """Get environment variables collection."""
256
    
257
    def env_var(self, env_var_name: str) -> ActorEnvVarClient:
258
        """Get specific environment variable client."""
259

260
class ActorVersionClientAsync:
261
    """Async version of ActorVersionClient with identical methods."""
262

263
class ActorVersionCollectionClient:
264
    def list(self) -> ListPage[dict]:
265
        """List Actor versions."""
266
    
267
    def create(self, **kwargs) -> dict:
268
        """Create new Actor version.
269
        
270
        Args:
271
            version_number (str): Version number
272
            source_type (str, optional): Source code type
273
            **kwargs: Version configuration
274
        """
275

276
class ActorVersionCollectionClientAsync:
277
    """Async version of ActorVersionCollectionClient with identical methods."""
278
```
279

280
### Environment Variable Management
281

282
Management of Actor environment variables with support for secret values.
283

284
```python { .api }
285
class ActorEnvVarClient:
286
    def get(self) -> dict | None:
287
        """Get environment variable."""
288
    
289
    def update(self, *, is_secret: bool | None, name: str, value: str) -> dict:
290
        """Update environment variable.
291
        
292
        Args:
293
            is_secret: Whether the value should be treated as secret
294
            name: Variable name
295
            value: Variable value
296
        """
297
    
298
    def delete(self) -> None:
299
        """Delete environment variable."""
300

301
class ActorEnvVarClientAsync:
302
    """Async version of ActorEnvVarClient with identical methods."""
303

304
class ActorEnvVarCollectionClient:
305
    def list(self) -> ListPage[dict]:
306
        """List Actor environment variables."""
307
    
308
    def create(self, *, is_secret: bool | None, name: str, value: str) -> dict:
309
        """Create new environment variable.
310
        
311
        Args:
312
            is_secret: Whether the value should be treated as secret
313
            name: Variable name
314
            value: Variable value
315
        """
316

317
class ActorEnvVarCollectionClientAsync:
318
    """Async version of ActorEnvVarCollectionClient with identical methods."""
319
```
320

321
## Usage Examples
322

323
### Basic Actor Execution
324

325
```python
326
from apify_client import ApifyClient
327

328
client = ApifyClient('your-api-token')
329

330
# Get Actor client
331
actor = client.actor('john-doe/web-scraper')
332

333
# Start Actor and wait for completion
334
run = actor.call(run_input={
335
    'startUrls': ['https://example.com'],
336
    'maxPages': 10
337
})
338

339
print(f"Run finished with status: {run['status']}")
340
```
341

342
### Actor Management
343

344
```python
345
# Create new Actor
346
new_actor = client.actors().create(
347
    name='my-scraper',
348
    title='My Web Scraper',
349
    description='Custom web scraping solution'
350
)
351

352
# Update Actor configuration
353
actor = client.actor(new_actor['id'])
354
actor.update(
355
    title='Updated Web Scraper',
356
    description='Enhanced web scraping solution with new features'
357
)
358

359
# Build Actor
360
build = actor.build()
361
print(f"Build started: {build['id']}")
362
```
363

364
### Environment Variables
365

366
```python
367
# Add environment variable to Actor version
368
version = client.actor('actor-id').version('1.0')
369
env_vars = version.env_vars()
370

371
env_vars.create(
372
    name='API_KEY',
373
    value='secret-api-key',
374
    is_secret=True
375
)
376

377
# List all environment variables
378
vars_list = env_vars.list()
379
for var in vars_list.items:
380
    print(f"{var['name']}: {'[SECRET]' if var['isSecret'] else var['value']}")
381
```