From 340490be15d90b0679cdf51ddabe28a4b85fab3b Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 13 Jan 2026 12:55:33 +0100 Subject: [PATCH 1/6] docs: update state persistence section to clarify usage of Actor.useState method --- .../actors/development/builds_and_runs/state_persistence.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index 218b88f387..079e105c8b 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -47,9 +47,9 @@ By default, an Actor keeps its state in the server's memory. During a server swi ## Implementing state persistence -The [Apify SDKs](/sdk) handle state persistence automatically. +The simplest way to handle state persistence is with the [`Actor.useState`](/sdk/js/reference/class/Actor#useState) method, which automatically saves and retrieves your state during migrations. -This is done using the `Actor.on()` method and the `migrating` event. +For more control or when using Python, you can manually handle state persistence using the `Actor.on()` method and the `migrating` event. - The `migrating` event is triggered just before a migration occurs, allowing you to save your state. - To retrieve previously saved state, you can use the [`Actor.getValue`](/sdk/js/reference/class/Actor#getValue)/[`Actor.get_value`](/sdk/python/reference/class/Actor#get_value) methods. From e9d608a3a41f172fb0aaa50fb1882b314515d408 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 15 Jan 2026 07:46:19 +0100 Subject: [PATCH 2/6] Update sources/platform/actors/development/builds_and_runs/state_persistence.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> --- .../actors/development/builds_and_runs/state_persistence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index 079e105c8b..abe29d3292 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -47,7 +47,7 @@ By default, an Actor keeps its state in the server's memory. During a server swi ## Implementing state persistence -The simplest way to handle state persistence is with the [`Actor.useState`](/sdk/js/reference/class/Actor#useState) method, which automatically saves and retrieves your state during migrations. +To handle state persistence, use the [`Actor.useState()`](/sdk/js/reference/class/Actor#useState) method. This method automatically saves and retrieves your state during migrations. For more control or when using Python, you can manually handle state persistence using the `Actor.on()` method and the `migrating` event. From 5f9cd6dfa08a7ed9dbdcdbbe91c0c9c52880109c Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 3 Mar 2026 11:59:10 +0100 Subject: [PATCH 3/6] docs: streamline state persistence instructions and examples for Actors --- .../builds_and_runs/state_persistence.md | 71 ++++--------------- 1 file changed, 14 insertions(+), 57 deletions(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index abe29d3292..fe64265ac4 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -13,11 +13,7 @@ import TabItem from '@theme/TabItem'; Long-running [Actor](../../index.mdx) jobs may need to migrate between servers. Without state persistence, your job's progress is lost during migration, causing it to restart from the beginning on the new server. This can be costly and time-consuming. -To prevent data loss, long-running Actors should: - -- Periodically save (persist) their state. -- Listen for [migration events](/sdk/js/api/apify/class/PlatformEventManager) -- Check for persisted state when starting, allowing them to resume from where they left off. +To prevent data loss, long-running Actors should persist their state so they can resume from where they left off after a migration. For short-running Actors, the risk of restarts and the cost of repeated runs are low, so you can typically ignore state persistence. @@ -47,16 +43,7 @@ By default, an Actor keeps its state in the server's memory. During a server swi ## Implementing state persistence -To handle state persistence, use the [`Actor.useState()`](/sdk/js/reference/class/Actor#useState) method. This method automatically saves and retrieves your state during migrations. - -For more control or when using Python, you can manually handle state persistence using the `Actor.on()` method and the `migrating` event. - -- The `migrating` event is triggered just before a migration occurs, allowing you to save your state. -- To retrieve previously saved state, you can use the [`Actor.getValue`](/sdk/js/reference/class/Actor#getValue)/[`Actor.get_value`](/sdk/python/reference/class/Actor#get_value) methods. - -### Code examples - -To manually persist state, use the `Actor.on` method in the Apify SDK: +Use the [`Actor.useState()`](/sdk/js/reference/class/Actor#useState)/[`Actor.use_state()`](/sdk/python/reference/class/Actor#use_state) method to persist state across migrations. This method automatically saves your state to the key-value store and restores it when the Actor restarts. @@ -65,47 +52,14 @@ To manually persist state, use the `Actor.on` method in the Apify SDK: import { Actor } from 'apify'; await Actor.init(); -// ... -Actor.on('migrating', () => { - Actor.setValue('my-crawling-state', { - foo: 'bar', - }); -}); -// ... -await Actor.exit(); -``` - - - -```python -from apify import Actor, Event +const state = await Actor.useState({ itemCount: 0, lastOffset: 0 }); -async def actor_migrate(_event_data): - await Actor.set_value('my-crawling-state', {'foo': 'bar'}) +// The state object is automatically persisted during migrations. +// Update it as your Actor processes data. +state.itemCount += 1; +state.lastOffset = 100; -async def main(): - async with Actor: - # ... - Actor.on(Event.MIGRATING, actor_migrate) - # ... -``` - - - - -To check for state saved in a previous run: - - - - -```js -import { Actor } from 'apify'; - -await Actor.init(); -// ... -const previousCrawlingState = await Actor.getValue('my-crawling-state') || {}; -// ... await Actor.exit(); ``` @@ -117,15 +71,18 @@ from apify import Actor async def main(): async with Actor: - # ... - previous_crawling_state = await Actor.get_value('my-crawling-state') - # ... + state = await Actor.use_state({'item_count': 0, 'last_offset': 0}) + + # The state object is automatically persisted during migrations. + # Update it as your Actor processes data. + state['item_count'] += 1 + state['last_offset'] = 100 ``` -For improved Actor performance consider [caching repeated page data](/academy/expert-scraping-with-apify/saving-useful-stats). +For improved Actor performance, consider [caching repeated page data](/academy/expert-scraping-with-apify/saving-useful-stats). ## Speeding up migrations From 4a1e053cbfef4e53ff0ab5199fdfd622e9b77164 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 3 Mar 2026 14:19:13 +0100 Subject: [PATCH 4/6] review suggestion --- .../actors/development/builds_and_runs/state_persistence.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index fe64265ac4..8ecc0db630 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -87,8 +87,7 @@ For improved Actor performance, consider [caching repeated page data](/academy/e ## Speeding up migrations Once your Actor receives the `migrating` event, the Apify platform will shut it down and restart it on a new server within one minute. -To speed this process up, once you have persisted the Actor state, -you can manually reboot the Actor in the `migrating` event handler using the `Actor.reboot()` method +To speed this process up and ensure state consistency, you can manually reboot the Actor in the `migrating` event handler using the `Actor.reboot()` method available in the [Apify SDK for JavaScript](/sdk/js/reference/class/Actor#reboot) or [Apify SDK for Python](/sdk/python/reference/class/Actor#reboot). From c1da0d538402f69505dc7a8195d107b7b8879e19 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Tue, 3 Mar 2026 14:21:44 +0100 Subject: [PATCH 5/6] docs: refine state persistence section for clarity and consistency --- .../actors/development/builds_and_runs/state_persistence.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index 8ecc0db630..3cd3ee6c2f 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -41,7 +41,7 @@ Migrations don't follow a specific schedule. They can occur at any time due to t By default, an Actor keeps its state in the server's memory. During a server switch, the run loses access to the previous server's memory. Even if data were saved on the server's disk, access to that would also be lost. Note that the Actor run's default dataset, key-value store and request queue are preserved across migrations, by state we mean the contents of runtime variables in the Actor's code. -## Implementing state persistence +## Implement state persistence Use the [`Actor.useState()`](/sdk/js/reference/class/Actor#useState)/[`Actor.use_state()`](/sdk/python/reference/class/Actor#use_state) method to persist state across migrations. This method automatically saves your state to the key-value store and restores it when the Actor restarts. @@ -84,7 +84,7 @@ async def main(): For improved Actor performance, consider [caching repeated page data](/academy/expert-scraping-with-apify/saving-useful-stats). -## Speeding up migrations +## Speed up migrations and ensure consistency Once your Actor receives the `migrating` event, the Apify platform will shut it down and restart it on a new server within one minute. To speed this process up and ensure state consistency, you can manually reboot the Actor in the `migrating` event handler using the `Actor.reboot()` method From d70cbd92896bf86544664856a539c74003673974 Mon Sep 17 00:00:00 2001 From: Marcel Rebro Date: Thu, 5 Mar 2026 10:16:40 +0100 Subject: [PATCH 6/6] Update sources/platform/actors/development/builds_and_runs/state_persistence.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com> --- .../actors/development/builds_and_runs/state_persistence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/platform/actors/development/builds_and_runs/state_persistence.md b/sources/platform/actors/development/builds_and_runs/state_persistence.md index 3cd3ee6c2f..cf7bbfa0ad 100644 --- a/sources/platform/actors/development/builds_and_runs/state_persistence.md +++ b/sources/platform/actors/development/builds_and_runs/state_persistence.md @@ -43,7 +43,7 @@ By default, an Actor keeps its state in the server's memory. During a server swi ## Implement state persistence -Use the [`Actor.useState()`](/sdk/js/reference/class/Actor#useState)/[`Actor.use_state()`](/sdk/python/reference/class/Actor#use_state) method to persist state across migrations. This method automatically saves your state to the key-value store and restores it when the Actor restarts. +Use the JS SDK's [`Actor.useState()`](/sdk/js/reference/class/Actor#useState) or Python SDK's [`Actor.use_state()`](/sdk/python/reference/class/Actor#use_state) methods to persist state across migrations. This method automatically saves your state to the key-value store and restores it when the Actor restarts.