04_actor_events.mdx

id	actor-events
title	Actor events & state persistence
description	Handle platform events like state persistence and graceful shutdown in your Actors.

import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';

import ActorEventsExample from '!!raw-loader!roa-loader!./code/04_actor_events.py'; import UseStateExample from '!!raw-loader!roa-loader!./code/04_use_state.py'; import ApiLink from '@theme/ApiLink';

During its runtime, the Actor receives Actor events sent by the Apify platform or generated by the Apify SDK itself.

Event types

A listener can optionally receive a single argument, a Pydantic model with the event's data. The following table lists the events, the type of that data object, and when each event is emitted.

Event	Data	Description
SYSTEM_INFO	EventSystemInfoData	Emitted regularly to report the Actor's current resource usage. The cpu_info.used_ratio field reports the fraction of CPU currently in use (a float between 0.0 and 1.0), and memory_info.current_size reports the current memory usage. Compare cpu_info.used_ratio against Configuration.max_used_cpu_ratio to detect CPU overload.
MIGRATING	EventMigratingData	Emitted when the Actor running on the Apify platform is going to be migrated {' '}to another worker server soon. The time_remaining field reports how much time the Actor has left before it is force-migrated. You can use it to persist the state of the Actor so that once it is executed again on the new server, it doesn't have to start over from the beginning. Once you have persisted the state of your Actor, you can call `Actor.reboot` to reboot the Actor and trigger the migration immediately, to speed up the process.
ABORTING	EventAbortingData	When a user aborts an Actor run on the Apify platform, they can choose to abort gracefully to allow the Actor some time before getting killed. This graceful abort emits the ABORTING event which you can use to finish all running tasks and do cleanup.
PERSIST_STATE	EventPersistStateData	Emitted in regular intervals (by default 60 seconds) to notify the Actor that it should persist its state, in order to avoid repeating all work when the Actor restarts. This event is also emitted automatically when the MIGRATING event happens, in which case the is_migrating flag is set to True. Note that the PERSIST_STATE event is provided merely for user convenience, you can achieve the same effect by persisting the state regularly in an interval and listening for the migrating event.
EXIT	EventExitData	Emitted by the SDK (not the platform) when the Actor is about to exit. You can use this event to perform final cleanup tasks, such as closing external connections or sending notifications, before the Actor shuts down.

Adding handlers to events

To add handlers to these events, you use the Actor.on method, and to remove them, you use the Actor.off method.

{ActorEventsExample}

Automatic state persistence

The example above shows how to manually persist state using the PERSIST_STATE event. For most use cases, you can use the Actor.use_state method instead, which handles state persistence automatically.

Actor.use_state returns a dictionary that is automatically saved to the default key-value store at regular intervals and whenever a migration or shutdown occurs. You can modify the dictionary in place, and changes are persisted without any manual set_value calls.

You can optionally specify a key (the key-value store key under which the state is stored) and a kvs_name (the name of the key-value store to use). By default, the state is stored in the default key-value store under a default key.

{UseStateExample}

Conclusion

This page has described the events emitted during a run (SYSTEM_INFO, MIGRATING, ABORTING, PERSIST_STATE, and EXIT): how to handle them with Actor.on, and how to persist state automatically with Actor.use_state.

For more details on platform events and state persistence, see the system events and state persistence documentation on the Apify platform.