feat: dynamic Actor memory #2145

danpoletaev · 2025-12-15T14:23:39Z

This PR adds documentation for the recently released Dynamic Actor Memory feature. I also added backlinks from related documentation sections.

More information in spec

Note

Documents dynamic Actor memory with defaultMemoryMbytes (int or expression), updates related docs, and extends OpenAPI Actor definition.

Docs:
- New: Dynamic memory guide at sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md (expressions, helpers, limits, testing via NPM/CLI).
- actor.json: Example and reference for defaultMemoryMbytes (supports dynamic expression strings).
- Running:
  - input_and_output.md: Info note explaining dynamic memory behavior and override via run option.
  - usage_and_resources.md: Clarify memory can be omitted to use Actor default (may be dynamic) and restate constraints.
OpenAPI:
- apify-api/openapi/components/schemas/actors/ActorDefinition.yaml: Add defaultMemoryMbytes (oneOf integer|string) with description.

^{Written by Cursor Bugbot for commit 0305a25. Configure here.}

apify-service-account · 2025-12-15T14:26:56Z

Preview for this PR was built for commit 0305a25 and is ready at https://pr-2145.preview.docs.apify.com!

apify-service-account · 2025-12-15T14:29:54Z

Preview for this PR was built for commit 6f1618d and is ready at https://pr-2145.preview.docs.apify.com!

apify-api/openapi/components/schemas/actors/ActorDefinition.yaml

apify-service-account · 2025-12-16T09:24:46Z

Preview for this PR was built for commit 90f48e9 and is ready at https://pr-2145.preview.docs.apify.com!

apify-service-account · 2025-12-16T09:30:13Z

Preview for this PR was built for commit e203dce and is ready at https://pr-2145.preview.docs.apify.com!

apify-service-account · 2025-12-16T10:26:28Z

Preview for this PR was built for commit b3e4628 and is ready at https://pr-2145.preview.docs.apify.com!

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

apify-service-account · 2025-12-18T09:25:09Z

Preview for this PR was built for commit 133af16c and is ready at https://pr-2145.preview.docs.apify.com!

apify-service-account · 2025-12-18T09:35:06Z

Preview for this PR was built for commit 52099e77 and is ready at https://pr-2145.preview.docs.apify.com!

janbuchar · 2025-12-18T09:42:07Z

apify-api/openapi/components/schemas/actors/ActorDefinition.yaml

This component is only used in the Build component, which is only returned from "get build", "build actor" and "abort actor build" endpoints - its that correct?

Yes, correct

tobice

Sorry, forgot to submit my review 🤦

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

tobice · 2025-12-16T08:50:30Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+:::
+
+---
+


(opt) I'm kind of missing here a section How dynamic memory works.

First of all, we should double-down on the fact that dynamic does not mean that the Actor can on-the-fly ask for more memory. IMHO this is easily confused (we have seen it even internally).

Second, it should explain the whole "memory configuration pipeline", as in, how is memory for a run determined (memory expression vs Actor defaults vs run overrides).

Good point, refactored it 👍

tobice · 2025-12-16T08:50:59Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+Dynamic Actor memory allows Actors to _automatically adjust its memory allocation based on the input and run options_. Instead of always using a fixed memory value, Actor can use just the right amount of memory for each run.
+
+This helps:


(nit) This is kind of overlapping with Why dynamic memory matters.

tobice · 2025-12-16T08:51:50Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+---
+
+### Writing Expressions


(nit) I don't think you need this headline, it can be merged with the previous section.

tobice · 2025-12-16T08:52:59Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+}
+```
+
+- The expression is evaluated _before the run starts_.


(nit) This is not really related how to define the expression, but rather how it works. See my suggestion above.

tobice · 2025-12-16T08:56:45Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+### Example expressions
+
+1. Simple memory based on URL count


Suggested change

1. Simple memory based on URL count

1. Memory based on URL count

The "simple" sounds weird.

tobice · 2025-12-16T08:57:45Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+```js
+get(input, 'startUrls.length', 1) * 512
+```
+1. Conditional logic


Suggested change

1. Conditional logic

1. Increase memory if the user wants to scrape additional details

(nit) Maybe instead of a generic headline that doesn't say much explain what the expression actually does?

I kind of struggle with interpreting the expressions and I'll hardly be the only one 😄 This can help.

Dtt below.

Refactored this

tobice · 2025-12-16T08:59:51Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+1. More complex calculation
+
+```js
+urls = get(input, 'startUrls.length', 0);


Suggested change

urls = get(input, 'startUrls.length', 0);

urlCount = get(input, 'startUrls.length', 0);

tobice · 2025-12-16T09:02:33Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+---
+
+### Key Takeaways


(opt) Is this needed? Is such a section something that we usually do?

not really, and even if we would do it it shouldn't have been in Title case rather in Sentence case

removed key takeaways

tobice · 2025-12-16T09:03:11Z

sources/platform/actors/running/input_and_output.md

 | Memory | Amount of memory allocated for the Actor run, in megabytes. |

+:::info Dynamic memory
+If the Actor is configured by developer to use [dynamic memory](../development/actor_definition/dynamic_actor_memory/index.md), the system will calculate the optimal memory allocation based on your input. In this case, the **Memory** option acts as an override - if you set it, the calculated value will be ignored.


Suggested change

If the Actor is configured by developer to use [dynamic memory](../development/actor_definition/dynamic_actor_memory/index.md), the system will calculate the optimal memory allocation based on your input. In this case, the **Memory** option acts as an override - if you set it, the calculated value will be ignored.

If the Actor is configured by developer to use [dynamic memory](../development/actor_definition/dynamic_actor_memory/index.md), the system will calculate the optimal memory allocation based on your input. In this case, the **Memory** option acts as an override — if you set it, the calculated value will be ignored.

marcel-rbro · 2025-12-19T08:24:40Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+### Memory limits and clamping
+
+After evaluation:
+
+1. The result is rounded up to the nearest power of two
+
+    - 900 → 1024 MB
+    - 3,600 → 4096 MB
+
+2. It is clamped to actor-defined min/max (`minMemoryMbytes` / `maxMemoryMbytes`).
+3. It is clamped to platform limits (128 MB to 32 GB).


One more thing. Why use the word "clamp" here? Is there a specific reason? Otherwise, I'd just go with limits, not clamping:

Suggested change

### Memory limits and clamping

After evaluation:

1. The result is rounded up to the nearest power of two

- 900 → 1024 MB

- 3,600 → 4096 MB

2. It is clamped to actor-defined min/max (`minMemoryMbytes` / `maxMemoryMbytes`).

3. It is clamped to platform limits (128 MB to 32 GB).

### Memory limits

After the expression is evaluated, the memory value goes through these steps:

1. The result is rounded up to the nearest power of two

- 900 → 1024 MB

- 3,600 → 4096 MB

2. If the Actor has minimum or maximum memory limits defined (`minMemoryMbytes` / `maxMemoryMbytes`), the value is adjusted to stay within those limits.

3. The value is adjusted to stay within platform limits (128 MB to 32 GB).

Also we should be using only 1. to create ordered lists. It makes maintenance much easier

janbuchar

The OpenAPI part looks good to me

TC-MO

Left few comments as well

TC-MO · 2025-12-19T11:30:37Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+### Example expressions
+
+#### Simple memory based on URL count
+
+```js
+get(input, 'startUrls.length', 1) * 512
+```
+
+#### Conditional logic
+
+```js
+get(input, 'scrapeDetailed', false) ? 4096 : 1024
+```
+
+#### More complex calculation
+
+```js
+urls = get(input, 'startUrls.length', 0);
+reviewsMultiplier = max(get(input, 'maxReviews', 1) / 10, 1);
+urls * reviewsMultiplier * 128
+```
+
+#### Using double-brace variables
+
+```js
+{{input.itemsToProcess}} * 64
+```


Maybe we can use Tabs component here?

Good point, refactored it

TC-MO · 2025-12-19T11:31:10Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+---
+
+### Key Takeaways


not really, and even if we would do it it shouldn't have been in Title case rather in Sentence case

TC-MO · 2025-12-19T11:32:11Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+apify actor calculate-memory --input ./input.json --maxTotalChargeUsd=25
+```
+
+---


Any reason why there are these lines to break the page? we do it once to at the beginning usually to provide TL:DR of what the page is about but do not use it later for page break

TC-MO · 2025-12-19T11:33:52Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+
+You can use [Apify CLI](https://docs.apify.com/cli) to quickly evaluate expressions without writing code. It supports reading input from a JSON file and passing run options as flags.
+
+```shell


I think this is not correct language declaration for code block. IIRC it's based on Prism.js and in such cases bash is generally used (this is valid for whole document)

TC-MO · 2025-12-19T11:34:49Z

sources/platform/actors/development/actor_definition/dynamic_actor_memory/index.md

+### Memory limits and clamping
+
+After evaluation:
+
+1. The result is rounded up to the nearest power of two
+
+    - 900 → 1024 MB
+    - 3,600 → 4096 MB
+
+2. It is clamped to actor-defined min/max (`minMemoryMbytes` / `maxMemoryMbytes`).
+3. It is clamped to platform limits (128 MB to 32 GB).


Also we should be using only 1. to create ordered lists. It makes maintenance much easier

apify-service-account · 2025-12-19T14:00:01Z

Preview for this PR was built for commit 7ab0ccc9 and is ready at https://pr-2145.preview.docs.apify.com!

apify-service-account · 2025-12-19T14:17:53Z

Preview for this PR was built for commit 50b78baa and is ready at https://pr-2145.preview.docs.apify.com!

danpoletaev added 2 commits December 15, 2025 15:01

feat: dynamic actor memory

35307a4

chore: add backlinks

0305a25

danpoletaev requested review from TC-MO, marcel-rbro, raethlo and tobice December 15, 2025 14:23

danpoletaev self-assigned this Dec 15, 2025

danpoletaev added the adhoc Ad-hoc unplanned task added during the sprint. label Dec 15, 2025

danpoletaev requested review from fnesveda and janbuchar as code owners December 15, 2025 14:23

danpoletaev removed request for fnesveda and janbuchar December 15, 2025 14:23

chore: fix lint

6f1618d

janbuchar reviewed Dec 15, 2025

View reviewed changes

apify-api/openapi/components/schemas/actors/ActorDefinition.yaml Outdated Show resolved Hide resolved

refactor: clean up

90f48e9

refactor: clean up

e203dce

refactor: clean up

b3e4628

marcel-rbro requested changes Dec 17, 2025

View reviewed changes

refactor: clean up

133af16

github-actions bot added this to the 130th sprint - Core Services team milestone Dec 18, 2025

github-actions bot added the t-core-services Issues with this label are in the ownership of the core services team. label Dec 18, 2025

fix: lint

52099e7

janbuchar reviewed Dec 18, 2025

View reviewed changes

tobice requested changes Dec 18, 2025

View reviewed changes

marcel-rbro requested changes Dec 19, 2025

View reviewed changes

janbuchar approved these changes Dec 19, 2025

View reviewed changes

TC-MO reviewed Dec 19, 2025

View reviewed changes

danpoletaev added 2 commits December 19, 2025 14:56

refactor: clean up

9e853c8

fix: lint

7ab0ccc

danpoletaev added 2 commits December 19, 2025 15:03

refactor: clean up

2f7561c

refactor: clean up

50b78ba

danpoletaev requested review from marcel-rbro and tobice December 19, 2025 14:15


		Dynamic Actor memory allows Actors to _automatically adjust its memory allocation based on the input and run options_. Instead of always using a fixed memory value, Actor can use just the right amount of memory for each run.

		This helps:

	1. Simple memory based on URL count
	1. Memory based on URL count

	1. Conditional logic
	1. Increase memory if the user wants to scrape additional details

	urls = get(input, 'startUrls.length', 0);
	urlCount = get(input, 'startUrls.length', 0);

	If the Actor is configured by developer to use [dynamic memory](../development/actor_definition/dynamic_actor_memory/index.md), the system will calculate the optimal memory allocation based on your input. In this case, the Memory option acts as an override - if you set it, the calculated value will be ignored.
	If the Actor is configured by developer to use [dynamic memory](../development/actor_definition/dynamic_actor_memory/index.md), the system will calculate the optimal memory allocation based on your input. In this case, the Memory option acts as an override — if you set it, the calculated value will be ignored.


		You can use [Apify CLI](https://docs.apify.com/cli) to quickly evaluate expressions without writing code. It supports reading input from a JSON file and passing run options as flags.

		```shell

		:::

		---

feat: dynamic Actor memory #2145

Are you sure you want to change the base?

feat: dynamic Actor memory #2145

Conversation

danpoletaev commented Dec 15, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented Dec 15, 2025

Uh oh!

apify-service-account commented Dec 15, 2025

Uh oh!

Uh oh!

apify-service-account commented Dec 16, 2025

Uh oh!

apify-service-account commented Dec 16, 2025

Uh oh!

apify-service-account commented Dec 16, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apify-service-account commented Dec 18, 2025

Uh oh!

apify-service-account commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tobice left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbuchar left a comment

Choose a reason for hiding this comment

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danpoletaev commented Dec 15, 2025 •

edited by cursor bot

Loading

TC-MO Dec 19, 2025 •

edited

Loading