docs: add PPE event charging examples and restructure best practices by TC-MO · Pull Request #2263 · apify/apify-docs

TC-MO · 2026-02-19T08:12:17Z

Add three generic Actor.charge() examples (JS + Python) to the PPE docs:

Charge per result with spending limit check
Charge for multiple event types
Charge for multiple items at once using count parameter

Move "Respect user spending limits" from standalone section into best practices and reorder subsections for logical flow: setup, spending limits, charging patterns, then pricing guidance. Clean up best practices intro prose.

marcel-rbro

Some questions and suggestions, overall looks good.

marcel-rbro · 2026-02-19T14:48:07Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

+### Charge for multiple event types

-When using [Crawlee](https://crawlee.dev/), use `crawler.autoscaledPool.abort()` instead of `Actor.exit()` to gracefully finish the crawler and allow the rest of your code to process normally.
+Charge multiple event types in a single operation. Each event type must be defined in your Actor's pricing configuration.


Maybe explain this more thoroughly? The text says "charge multiple event types in a single operation", but the example shows two charge calls. Maybe rewrite to something like: "Charge for multiple different event types in one Actor run"?

marcel-rbro · 2026-02-19T14:50:36Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

-The Apify SDK's `ChargeResult` respects the user set limit already.
+Users set a spending limit through the Apify Console. This limit is available in your Actor code as the `ACTOR_MAX_TOTAL_CHARGE_USD` [environment variable](/platform/actors/development/programming-interface/environment-variables). The Apify SDK's `ChargeResult` respects this limit automatically.
+
+When using [Crawlee](https://crawlee.dev/), use `crawler.autoscaledPool.abort()` instead of `Actor.exit()` to gracefully finish the crawler.


Is this the correct place for the Crawlee note? The admonition title doesn't fit with this.

Yeah I was trying to avoid two admonitions next to each other and may have went overboard with streamlining. Maybe this will be better as regular prose 🤔

marcel-rbro · 2026-02-19T14:52:18Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

 if (chargeResult.eventChargeLimitReached) {
-  await Actor.exit();
+    await Actor.exit();
 }


This is the only example that shows this method. Should it be added to the 2 other examples below?

On one hand it could be, on the other it would make all of those repetitive. My goal here was to create generic code examples, that span few use-cases. Kind of in a way to teach, but not provide production-ready code.

marcel-rbro · 2026-02-19T14:55:44Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

+### Charge for multiple items at once

-#### Synthetic start event for existing Actors
+Use the `count` parameter to charge for a batch of items in a single call.


How to handle eventChargeLimitReached in this case? Or is that outside of the scope of this task? 😆

marcel-rbro · 2026-02-19T14:57:12Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx


-When using [Crawlee](https://crawlee.dev/), use `crawler.autoscaledPool.abort()` instead of `Actor.exit()` to gracefully finish the crawler and allow the rest of your code to process normally.
+Charge multiple event types in a single operation. Each event type must be defined in your Actor's pricing configuration.



If you have multiple events, use the chargeableWithinLimit property to see if other events can still be charged before stopping the Actor.

But it's not demonstrated anywhere?

Yeah my starting point was more complex code example and then I started simplifying it, might be the best to remove mention from prose

- Fix "single operation" wording to "in one Actor run" - Move Crawlee note out of ACTOR_MAX_TOTAL_CHARGE_USD admonition into prose - Removed chargeableWithinLimit mention from prose - Add chargedCount handling to batch charging example Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Patai5 · 2026-03-04T10:23:09Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

+const data = { url: 'https://example.com', title: 'Example' };
+const chargeResult = await Actor.charge({ eventName: 'result' });

 if (chargeResult.eventChargeLimitReached) {
-  await Actor.exit();
+    await Actor.exit();
 }

-// Rest of the Actor logic
+await Actor.pushData(data);


Just from a coding standards perspective, it is recommended to keep variables as close as possible to where they are first used. So we could initialize the data right before pushing it 👀

Suggested change

const data = { url: 'https://example.com', title: 'Example' };

const chargeResult = await Actor.charge({ eventName: 'result' });

if (chargeResult.eventChargeLimitReached) {

await Actor.exit();

await Actor.exit();

}

// Rest of the Actor logic

await Actor.pushData(data);

const chargeResult = await Actor.charge({ eventName: 'result' });

if (chargeResult.eventChargeLimitReached) {

await Actor.exit();

}

const data = { url: 'https://example.com', title: 'Example' };

await Actor.pushData(data);

(this applies to the other examples as well)

Add three generic Actor.charge() examples (JS + Python) to the PPE docs: - Charge per result with spending limit check - Charge for multiple event types - Charge for multiple items at once using count parameter Move "Respect user spending limits" from standalone section into best practices and reorder subsections for logical flow: setup, spending limits, charging patterns, then pricing guidance. Clean up best practices intro prose. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Fix "single operation" wording to "in one Actor run" - Move Crawlee note out of ACTOR_MAX_TOTAL_CHARGE_USD admonition into prose - Removed chargeableWithinLimit mention from prose - Add chargedCount handling to batch charging example Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apify-service-account · 2026-03-05T12:52:26Z

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

Separates implementation patterns from best practices to support two distinct reader modes: evaluators reading principles vs. implementers looking for working code. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Adds a 'Respect spending limits' code example showing eventChargeLimitReached in a loop and chargeableWithinLimit for multi-event Actors. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Reorders examples simple-to-complex: basic charging patterns first, limit handling last as the advanced safety wrapper. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

apify-service-account · 2026-03-06T22:01:36Z

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

apify-service-account · 2026-03-07T00:06:28Z

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

apify-service-account · 2026-03-19T16:20:09Z

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

vdusek · 2026-03-20T14:27:52Z

sources/platform/actors/publishing/monetize/pay_per_event.mdx

+        # chargeable_within_limit lists event types the user's budget still covers
+        if 'result' not in charge_result.chargeable_within_limit:
+            await Actor.exit('Spending limit reached')


I believe the charge_result contains how many events of each type can still be charged. Meaning all registered event types are always present as keys with a value of 0 when exhausted. So this check won't work because the key is always there.

It might probably look something like this:

Suggested change

# chargeable_within_limit lists event types the user's budget still covers

if 'result' not in charge_result.chargeable_within_limit:

await Actor.exit('Spending limit reached')

# chargeable_within_limit maps event names to remaining counts (None means unlimited)

remaining = charge_result.chargeable_within_limit.get('result', 0)

if remaining is not None and remaining <= 0:

await Actor.exit('Spending limit reached')

The other examples look good to me. However, @janbuchar has better insight into the PPE implementation. Honzo, could you please double-check the examples? Also, there might be a similar issue like this in the JS version as well.

TC-MO self-assigned this Feb 19, 2026

TC-MO requested a review from marcel-rbro February 19, 2026 09:56

TC-MO added documentation Improvements or additions to documentation. t-docs Issues owned by technical writing team. labels Feb 19, 2026

marcel-rbro requested changes Feb 19, 2026

View reviewed changes

Patai5 reviewed Mar 4, 2026

View reviewed changes

TC-MO and others added 2 commits March 5, 2026 13:47

TC-MO force-pushed the add-event-examples branch from 4930479 to 00ecad4 Compare March 5, 2026 12:48

TC-MO and others added 3 commits March 5, 2026 14:06

docs: add spending limits code example to PPE docs

92f6ed1

Adds a 'Respect spending limits' code example showing eventChargeLimitReached in a loop and chargeableWithinLimit for multi-event Actors. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

docs: move spending limits example to end of code examples section

e8c3356

Reorders examples simple-to-complex: basic charging patterns first, limit handling last as the advanced safety wrapper. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

danpoletaev pushed a commit that referenced this pull request Mar 6, 2026

docs: address PR #2263 review feedback on PPE examples

60efc65

danpoletaev force-pushed the add-event-examples branch from 00ecad4 to 60efc65 Compare March 6, 2026 21:56

metalwarrior665 force-pushed the add-event-examples branch from 60efc65 to 00ecad4 Compare March 7, 2026 00:02

vdusek reviewed Mar 20, 2026

View reviewed changes


		When using [Crawlee](https://crawlee.dev/), use `crawler.autoscaledPool.abort()` instead of `Actor.exit()` to gracefully finish the crawler and allow the rest of your code to process normally.
		Charge multiple event types in a single operation. Each event type must be defined in your Actor's pricing configuration.

Conversation

TC-MO commented Feb 19, 2026

Uh oh!

marcel-rbro left a comment

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!

apify-service-account commented Mar 5, 2026

Uh oh!

apify-service-account commented Mar 6, 2026

Uh oh!

apify-service-account commented Mar 7, 2026

Uh oh!

apify-service-account commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants