docs: add Apify Actor run example task page by Jakub-Vacek · Pull Request #5021 · triggerdotdev/trigger.dev

Jakub-Vacek · 2026-10-12T06:00:06Z

Pre-agreed with the Trigger.dev team on Discord: https://discord.com/channels/1066956501299777596/1534928934184157205

✅ Checklist

I have followed every step in the contributing guide
The PR title follows the convention.
I ran and tested the code works

Testing

Both task samples were run against a live Apify account (only APIFY_TOKEN set) on Trigger.dev Cloud, dev environment, SDK 4.7.3, apify-client 2.25.0:

Example 1 (apify-actor-run): run completes and returns the dataset items from Website Content Crawler.
Example 2 (apify-long-actor-run): the run pauses on wait.forToken() while the Actor works (about 2 s of compute out of about 21 s total), resumes on the Apify webhook and returns the dataset items.
Aborted Actor run, both examples: aborting the Actor in Apify fails the task with AbortTaskRunError and does not retry.
apify-client bundling: without build.external: ["apify-client"], the first API call fails with TypeError: ProxyAgent is not a constructor. With it, both examples work. The page documents this.

Docs:

npx mintlify broken-links in docs/: no broken links found.
Ran the docs locally (npm run dev in docs/) and checked the new page, the sidebar entry under "Example tasks", the row in the example tasks table and the in-page links.

Changelog

Added an example task page, docs/guides/examples/apify-actor-run.mdx, showing two ways to run an Apify Actor from a task:

Start the Actor and wait for it to finish, for Actors that finish in seconds.
Start the Actor with an Apify ad-hoc webhook pointing at a wait token URL, so the run pauses until the Actor finishes and the wait doesn't count towards compute.

The page imports the shared web scraping warning, and is linked from the example tasks table in docs/guides/introduction.mdx and the "Example tasks" group in docs/docs.json.

Screenshots

💯

changeset-bot · 2026-10-12T06:00:15Z

⚠️ No Changeset found

Latest commit: e754f8a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-10-12T06:00:27Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Repository UI
Review profile: CHILL
Plan: Advanced
Run ID: 7b05a93f-2e42-438c-941a-30a831507f26

📥 Commits

Reviewing files that changed from the base of the PR and between f9cde18 and e754f8a.

📒 Files selected for processing: 3

docs/docs.json
docs/guides/examples/apify-actor-run.mdx
docs/guides/introduction.mdx

🚧 Files skipped from review as they are similar to previous changes: 2

docs/guides/introduction.mdx
docs/guides/examples/apify-actor-run.mdx

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📜 Recent review details

🔇 Additional comments: 1

docs/docs.json: 1

640-640: LGTM!

Walkthrough

The documentation adds an Apify Actor run guide and links it from the example-task navigation and introduction. The guide covers shared client setup, a short-run task that waits for results, and a long-run task that resumes through a webhook. It also includes dashboard testing instructions and notes about cancellation, retries, and task-output limits.

Priority: ➖ Normal

Merge Risk: 🟡 Moderate · up to e754f

Retries may launch duplicate Apify work, causing unnecessary cost or repeated side effects; make the examples retry-safe before merging.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title is concise, specific, and accurately describes the main documentation change: adding an Apify Actor run example task page.
Description check		The description includes the checklist, detailed testing results, changelog, and screenshot. It does not include the template's "Closes #" line, but the missing issue reference is non-critical …
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description includes the checklist, detailed testing results, changelog, and screenshot. It does not include the template's "Closes #<issue>" line, but the missing issue reference is non-critical and the description is otherwise complete.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (3 skipped: 3 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

devin-ai-integration

Note

Newer findings are available below. Devin Review posted a newer report on this PR, in addition to the findings presented here.

Devin Review found 4 potential issues.

devin-ai-integration · 2026-10-22T07:39:28Z

task output limits

+
+    logger.info("Actor run finished", { runId: run.id, itemCount: items.length });
+
+    return { runId: run.id, datasetId: run.defaultDatasetId, items };


🟡 Large crawl results exceed task output limit

When a crawl returns over 10MB, apifyActorRun returns the items as task output. Trigger.dev rejects that output, so a successful Actor run ends in task failure; the webhook task has the same issue.

Learn more

Both example tasks fetch dataset items and return them as one task result. Trigger.dev documents a 10MB task-output limit in task output limits. The webhook variant also returns the complete item array at apifyLongActorRun. An Actor can produce large text or structured records even with a 1,000-item cap, so the item count does not bound the serialized output size.

Example: A crawl returns 1,000 items averaging 12KB each. Apify reports success, but returning roughly 12MB as a task result exceeds the Trigger.dev output limit.

Recommended fix: In both examples, return the dataset ID and run ID rather than the entire dataset, or explicitly limit and measure the returned data and explain how to fetch larger results separately.

Was this helpful? React with 👍 or 👎 to provide feedback.

added a note about the 10MB output limit and how to read large datasets

devin-ai-integration · 2026-10-22T07:39:30Z

documentation rules

+
+Add `apify-client` to [`external`](/config/config-file#external) in your `trigger.config.ts` file. When it's bundled, `apify-client` fails on its first API call with `TypeError: ProxyAgent is not a constructor`.
+
+```ts trigger.config.ts


🟡 TypeScript examples violate required fence tags

All four TypeScript examples use ts fences instead of the required typescript tag in documentation rules.

Learn more

The documentation rules require typescript for TypeScript code fences. Four fences in this page use ts, so fixing only the anchored fence leaves three violations.

Example: The config, shared client, synchronous task, and webhook task all open their code fences with ts.

Recommended fix: Change each of the four opening fences to typescript, keeping the file labels unchanged.

Was this helpful? React with 👍 or 👎 to provide feedback.

keeping ts, because the site uses ts almost everywhere

devin-ai-integration · 2026-10-22T07:39:31Z

+      throw new Error(`Actor run ${run.id} finished with status ${run.status}`);
+    }
+
+    const { items } = await apify.dataset(run.defaultDatasetId).listItems();


🔍 Check dataset pagination against actor result cap

Both tasks call listItems() once. Confirm its default page size and whether Actors can produce more items than that page; otherwise results are incomplete.

Was this helpful? React with 👍 or 👎 to provide feedback.

listItems() without limit returns all items, and maxItems: 1000 bounds the dataset, so one call is complete

devin-ai-integration · 2026-10-22T07:39:32Z

+
+- The webhook covers all four ways an Actor run can end, so a failed, aborted or timed-out Actor resumes your run with an error instead of leaving it waiting until the token times out.
+- `payloadTemplate` sends only `eventType` and `resource` (the Actor run). Whatever Apify posts to `token.url` becomes the token's result, so the `ApifyWebhookPayload` type matches this template, not Apify's default webhook payload.
+- The token `timeout` is longer than the Actor's `timeout`, so the Actor always finishes, and the webhook fires, before the token expires.


🔍 Webhook delivery has no guaranteed margin

The ten-minute gap between the Actor timeout and token expiry does not guarantee webhook delivery. A delayed callback expires the wait and retries the Actor.

Was this helpful? React with 👍 or 👎 to provide feedback.

Apify sends the webhook as soon as the run ends, so a 10-minute delay is unlikely. If it happens, the task retries, which the retry-safety note covers.

daveomri added 3 commits October 8, 2026 15:50

docs(apify): add Apify Actor run example guide

d514885

docs(apify): link the Apify actor run examples

e1da756

docs(apify): change wording and add utm token to console link

d1e54bd

Jakub-Vacek changed the title ~~Docs/735 actor run example task page~~ Docs/Apify actor run example task page Oct 12, 2026

Jakub-Vacek changed the title ~~Docs/Apify actor run example task page~~ docs/apify actor run example task page Oct 12, 2026

This comment was marked as resolved.

Sign in to view

docs: note that Apify Actor run examples aren't retry-safe

d40f824

Jakub-Vacek changed the title ~~docs/apify actor run example task page~~ docs: add Apify Actor run example task page Oct 12, 2026

Jakub-Vacek mentioned this pull request Oct 12, 2026

feat(apify): add Apify lead research example triggerdotdev/examples#153

Draft

marcel-rbro mentioned this pull request Oct 21, 2026

docs: create the trigger.dev docs apify/apify-docs#3069

Open

Jakub-Vacek marked this pull request as ready for review October 22, 2026 07:36

devin-ai-integration Bot reviewed Oct 22, 2026

View reviewed changes

docs(apify): note the 10MB task output limit for large datasets

f9cde18

This comment was marked as resolved.

Sign in to view

daveomri and others added 2 commits October 22, 2026 10:20

docs: link to the task output limit instead of quoting a size

b76064d

Merge branch 'main' into docs/735-actor-run-example-task-page

e754f8a


		logger.info("Actor run finished", { runId: run.id, itemCount: items.length });

		return { runId: run.id, datasetId: run.defaultDatasetId, items };


		Add `apify-client` to [`external`](/config/config-file#external) in your `trigger.config.ts` file. When it's bundled, `apify-client` fails on its first API call with `TypeError: ProxyAgent is not a constructor`.

		```ts trigger.config.ts

Conversation

Jakub-Vacek commented Oct 12, 2026

✅ Checklist

Testing

Changelog

Screenshots

Uh oh!

changeset-bot Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

coderabbitai Bot commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

daveomri Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

daveomri Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

daveomri Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

daveomri Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Oct 12, 2026 •

edited

Loading

coderabbitai Bot commented Oct 12, 2026 •

edited

Loading

devin-ai-integration Bot left a comment •

edited

Loading