feat: poll run status in run-actor (#48)

* feat: poll run status in run-actor

* test: add test for run-actor with wait-for-finish

* feat: replace node timeout with n8n timeout

* refactor: change run-actor related comments

Author: ngut37

nodes/Apify/__tests__/Apify.node.spec.ts

@@ -157,11 +157,11 @@ describe('Apify Node', () => {
 
 				const scope = nock('https://api.apify.com')
 					.get('/v2/acts/nFJndFXA5zjCTuudP')
-					.reply(200, { data: fixtures.getActorResult() })
+					.reply(200, fixtures.getActorResult())
 					.get('/v2/acts/nFJndFXA5zjCTuudP/builds/default')
-					.reply(200, { data: fixtures.getBuildResult() })
+					.reply(200, fixtures.getBuildResult())
 					.post('/v2/acts/nFJndFXA5zjCTuudP/runs')
-					.query({ waitForFinish: 60 })
+					.query({ waitForFinish: 0 })
 					.reply(200, mockRunActor);
 
 				const runActorWorkflow = require('./workflows/actors/run-actor.workflow.json');
@@ -181,6 +181,41 @@ describe('Apify Node', () => {
 
 				expect(scope.isDone()).toBe(true);
 			});
+
+			it('should run the run-actor workflow and wait for finish', async () => {
+				const mockRunActor = fixtures.runActorResult();
+				const mockFinishedRun = fixtures.getRunResult();
+
+				const scope = nock('https://api.apify.com')
+					.get('/v2/acts/nFJndFXA5zjCTuudP')
+					.reply(200, fixtures.getActorResult())
+					.get('/v2/acts/nFJndFXA5zjCTuudP/builds/default')
+					.reply(200, fixtures.getBuildResult())
+					.post('/v2/acts/nFJndFXA5zjCTuudP/runs')
+					.query({ waitForFinish: 0 })
+					.reply(200, mockRunActor)
+					.get('/v2/actor-runs/Icz6E0IHX0c40yEi7')
+					.reply(200, mockFinishedRun);
+
+				const runActorWorkflow = require('./workflows/actors/run-actor-wait-for-finish.workflow.json');
+				const { waitPromise } = await executeWorkflow({
+					credentialsHelper,
+					workflow: runActorWorkflow,
+				});
+				const result = await waitPromise.promise();
+
+				const nodeResults = getRunTaskDataByNodeName(result, 'Run actor');
+				expect(nodeResults.length).toBe(1);
+				const [nodeResult] = nodeResults;
+				expect(nodeResult.executionStatus).toBe('success');
+
+				const data = getTaskData(nodeResult);
+				// exptect polled terminal run as result
+				expect(data).not.toEqual(mockRunActor.data);
+				expect(data).toEqual(mockFinishedRun.data);
+
+				expect(scope.isDone()).toBe(true);
+			});
 		});
 		describe('scrape-single-url', () => {
 			it('should run the scrape-single-url workflow', async () => {

nodes/Apify/__tests__/utils/fixtures.ts

@@ -243,52 +243,135 @@ export const getLastRunResult = () => {
 	};
 };
 
+// without waitForFinish (waitForFinish = 0)
 export const runActorResult = () => {
 	return {
 		data: {
-			id: 'gbNI2e1oNCufgd5Rn',
+			id: 'Icz6E0IHX0c40yEi7',
 			actId: 'nFJndFXA5zjCTuudP',
 			userId: 'A9zwKYff2yyRmaqc9',
-			startedAt: '2025-06-16T23:30:42.255Z',
-			finishedAt: '2025-06-16T23:30:52.922Z',
+			startedAt: '2025-06-30T12:36:08.502Z',
+			finishedAt: null,
+			status: 'READY',
+			meta: {
+				origin: 'API',
+				userAgent: 'axios/1.7.4',
+			},
+			stats: {
+				inputBodyLen: 346,
+				migrationCount: 0,
+				rebootCount: 0,
+				restartCount: 0,
+				resurrectCount: 0,
+				computeUnits: 0,
+			},
+			options: {
+				build: 'latest',
+				timeoutSecs: 604800,
+				memoryMbytes: 1024,
+				maxTotalChargeUsd: 37.42362467983089,
+				diskMbytes: 2048,
+			},
+			buildId: 'DgGC7ZxWmZ0cnuNIy',
+			defaultKeyValueStoreId: 'dgt7oov3cthGsD4yq',
+			defaultDatasetId: '63kMAihbWVgBvEAZ2',
+			defaultRequestQueueId: 'cGohS4eFRrm2mItLx',
+			pricingInfo: {
+				pricingModel: 'PAY_PER_EVENT',
+				reasonForChange:
+					'We are introducing Store pricing discounts for this Actor and a new pricing model to give you more transparency and flexibility; more info in the follow-up email.',
+				minimalMaxTotalChargeUsd: 0.5,
+				createdAt: '2025-05-29T14:45:00.000Z',
+				startedAt: '2025-06-10T08:00:00.000Z',
+				apifyMarginPercentage: 0,
+				notifiedAboutChangeAt: '2025-06-10T08:00:00.000Z',
+				pricingPerEvent: {
+					actorChargeEvents: {
+						'actor-start': {
+							eventTitle: 'Actor start',
+							eventDescription: 'Flat fee for starting an Actor run.',
+							eventPriceUsd: 0.0015,
+						},
+						'search-page-scraped': {
+							eventTitle: 'Search results page scraped',
+							eventDescription: 'Cost per page of Google Search results successfully scraped.',
+							eventPriceUsd: 0.0035,
+						},
+						'ads-scraped': {
+							eventTitle: 'Add-on: Paid results (ads) extraction',
+							eventDescription:
+								'Extra cost per page for attempting to extract paid results (ads) from Google Search. This applies when the ads extraction feature is enabled, regardless of whether ads are found on the specific page.',
+							eventPriceUsd: 0.005,
+						},
+					},
+				},
+			},
+			chargedEventCounts: {
+				'actor-start': 0,
+				'search-page-scraped': 0,
+				'ads-scraped': 0,
+			},
+			platformUsageBillingModel: 'DEVELOPER',
+			accountedChargedEventCounts: {
+				'actor-start': 0,
+				'search-page-scraped': 0,
+				'ads-scraped': 0,
+			},
+			generalAccess: 'FOLLOW_USER_SETTING',
+			buildNumber: '0.0.166',
+			containerUrl: 'https://fttjdkagbv7c.runs.apify.net',
+			usageTotalUsd: 0,
+		},
+	};
+};
+
+export const getSuccessRunResult = () => {
+	return {
+		data: {
+			id: 'ZtmMxsnaxohefirDg',
+			actId: 'nFJndFXA5zjCTuudP',
+			userId: 'A9zwKYff2yyRmaqc9',
+			startedAt: '2025-06-30T12:35:16.689Z',
+			finishedAt: '2025-06-30T12:35:24.942Z',
 			status: 'SUCCEEDED',
-			statusMessage: 'Finished! Total 2 requests: 2 succeeded, 0 failed.',
+			statusMessage:
+				'Actor finished successfully. Processed 3 queries on 3 pages. Extracted: 110 organicResults, 0 paidResults, 0 paidProducts, 48 relatedQueries, 1 aiOverviews.',
 			isStatusMessageTerminal: true,
 			meta: {
 				origin: 'API',
 				userAgent: 'axios/1.7.4',
 			},
 			stats: {
-				inputBodyLen: 336,
+				inputBodyLen: 346,
 				migrationCount: 0,
 				rebootCount: 0,
 				restartCount: 0,
-				durationMillis: 10476,
+				durationMillis: 8137,
 				resurrectCount: 0,
-				runTimeSecs: 10.476,
+				runTimeSecs: 8.137,
 				metamorph: 0,
-				computeUnits: 0.00291,
-				memAvgBytes: 128424657.84661157,
-				memMaxBytes: 145063936,
-				memCurrentBytes: 0,
-				cpuAvgUsage: 15.432343907121574,
-				cpuMaxUsage: 91.47420111042567,
-				cpuCurrentUsage: 0,
-				netRxBytes: 620882,
-				netTxBytes: 467443,
+				computeUnits: 0.0022602777777777777,
+				memAvgBytes: 114593891.31194456,
+				memMaxBytes: 171585536,
+				memCurrentBytes: 171585536,
+				cpuAvgUsage: 41.576489958372534,
+				cpuMaxUsage: 112.53407249466952,
+				cpuCurrentUsage: 59.16827757125155,
+				netRxBytes: 539776,
+				netTxBytes: 503865,
 			},
 			options: {
 				build: 'latest',
 				timeoutSecs: 604800,
 				memoryMbytes: 1024,
-				maxTotalChargeUsd: 36.57444567272754,
+				maxTotalChargeUsd: 37.44156455943874,
 				diskMbytes: 2048,
 			},
-			buildId: 'da2D8ovPHWBN98zj2',
+			buildId: 'DgGC7ZxWmZ0cnuNIy',
 			exitCode: 0,
-			defaultKeyValueStoreId: 'K1AdT7nsdFw2ThD5J',
-			defaultDatasetId: '6kTQQ34S3DftNqbE5',
-			defaultRequestQueueId: '2cPPDy1XSk5k17yst',
+			defaultKeyValueStoreId: '4aoPkdUdfoRpf9w7E',
+			defaultDatasetId: 'U0hEU6N57UfDgqI98',
+			defaultRequestQueueId: 'qNGmAgPf3Pb50PhqC',
 			pricingInfo: {
 				pricingModel: 'PAY_PER_EVENT',
 				reasonForChange:
@@ -331,9 +414,10 @@ export const runActorResult = () => {
 				'ads-scraped': 0,
 			},
 			generalAccess: 'FOLLOW_USER_SETTING',
-			buildNumber: '0.0.165',
-			containerUrl: 'https://xds5z9sxx8sx.runs.apify.net',
+			buildNumber: '0.0.166',
+			containerUrl: 'https://mc9gwqvhjshq.runs.apify.net',
 			usageTotalUsd: 0.0015,
+			consoleUrl: 'https://console.apify.com/view/runs/ZtmMxsnaxohefirDg',
 		},
 	};
 };

nodes/Apify/__tests__/workflows/actors/run-actor-wait-for-finish.workflow.json

@@ -0,0 +1,43 @@
+{
+	"name": "Run actor and wait for finish - workflow",
+	"nodes": [
+		{
+			"parameters": {
+				"operation": "Run actor",
+				"actorId": {
+					"__rl": true,
+					"value": "nFJndFXA5zjCTuudP",
+					"mode": "list",
+					"cachedResultName": "Google Search Results Scraper",
+					"cachedResultUrl": "https://console.com/actors/nFJndFXA5zjCTuudP/input"
+				},
+				"waitForFinish": true,
+				"customBody": "{\n    \"maxPagesPerQuery\": 1,\n    \"resultsPerPage\": 2,\n    \"queries\": \"javascript\\ntypescript\"\n}"
+			},
+			"id": "8b21ab5d-baff-48f1-9512-831704fd2df4",
+			"name": "Run actor",
+			"type": "n8n-nodes-apify.apify",
+			"typeVersion": 1,
+			"position": [1460, 520],
+			"credentials": {
+				"apifyApi": {
+					"id": "dJAynKkN2pRqy3Ko",
+					"name": "Apify account"
+				}
+			}
+		}
+	],
+	"pinData": {},
+	"connections": {},
+	"active": false,
+	"settings": {
+		"executionOrder": "v1"
+	},
+	"versionId": "3407ee9f-0aac-4990-804f-702d06bbc85b",
+	"meta": {
+		"templateCredsSetupCompleted": true,
+		"instanceId": "3f65ba173ae28613be507e94c0a98de4375527c55e31b7fc173a4edee4e2ded3"
+	},
+	"id": "OFLCq8UoIVInQv2Y",
+	"tags": []
+}

nodes/Apify/__tests__/workflows/actors/run-actor.workflow.json

@@ -11,7 +11,7 @@
 					"cachedResultName": "Google Search Results Scraper",
 					"cachedResultUrl": "https://console.com/actors/nFJndFXA5zjCTuudP/input"
 				},
-				"waitForFinish": 60,
+				"waitForFinish": false,
 				"customBody": "{\n    \"maxPagesPerQuery\": 1,\n    \"resultsPerPage\": 2,\n    \"queries\": \"javascript\\ntypescript\"\n}"
 			},
 			"id": "8b21ab5d-baff-48f1-9512-831704fd2df4",

nodes/Apify/helpers/consts.ts

@@ -1,2 +1,4 @@
 export const WEB_CONTENT_SCRAPER_ACTOR_ID = 'aYG0l9s7dbB7j3gbS';
 export const APIFY_API_URL = 'https://api.apify.com';
+export const TERMINAL_RUN_STATUSES = ['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'];
+export const WAIT_FOR_FINISH_POLL_INTERVAL = 1000; //

nodes/Apify/resources/actors/run-actor/execute.ts

@@ -5,6 +5,7 @@ import {
 	NodeOperationError,
 } from 'n8n-workflow';
 import { apiRequest } from '../../genericFunctions';
+import * as helpers from '../../../helpers';
 
 export async function runActor(this: IExecuteFunctions, i: number): Promise<INodeExecutionData> {
 	const actorId = this.getNodeParameter('actorId', i, undefined, {
@@ -13,7 +14,7 @@ export async function runActor(this: IExecuteFunctions, i: number): Promise<INod
 	const timeout = this.getNodeParameter('timeout', i) as number | null;
 	const memory = this.getNodeParameter('memory', i) as number | null;
 	const buildParam = this.getNodeParameter('build', i) as string | null;
-	const waitForFinish = this.getNodeParameter('waitForFinish', i) as number | null;
+	const waitForFinish = this.getNodeParameter('waitForFinish', i) as boolean;
 	const rawStringifiedInput = this.getNodeParameter('customBody', i, '{}') as string;
 
 	let userInput: any;
@@ -61,13 +62,50 @@ export async function runActor(this: IExecuteFunctions, i: number): Promise<INod
 	if (timeout != null) qs.timeout = timeout;
 	if (memory != null) qs.memory = memory;
 	if (build?.buildTag) qs.build = build.buildTag;
-	if (waitForFinish != null) qs.waitForFinish = waitForFinish;
+	qs.waitForFinish = 0; // set initial run actor to not wait for finish
 
 	// 6. Run the actor
 	const run = await runActorApi.call(this, actorId, mergedInput, qs);
+	if (!run?.data?.id) {
+		throw new NodeApiError(this.getNode(), {
+			message: `Run ID not found after running the actor`,
+		});
+	}
+
+	// 7a. If waitForFinish is false, return the run data immediately
+	if (!waitForFinish) {
+		return {
+			json: { ...run.data },
+		};
+	}
 
+	// 7b. Start polling for run status until it reaches a terminal state
+	// This loop is infinite and will only stop when a terminal status is reached,
+	// or when the workflow maximum timeout is hit, as set in your n8n configuration.
+	const runId = run.data.id;
+	let lastRunData = run.data;
+	while (true) {
+		try {
+			const pollResult = await apiRequest.call(this, {
+				method: 'GET',
+				uri: `/v2/actor-runs/${runId}`,
+			});
+			const status = pollResult?.data?.status;
+			lastRunData = pollResult?.data;
+			if (helpers.consts.TERMINAL_RUN_STATUSES.includes(status)) {
+				break;
+			}
+		} catch (err) {
+			throw new NodeApiError(this.getNode(), {
+				message: `Error polling run status: ${err}`,
+			});
+		}
+		await new Promise((resolve) =>
+			setTimeout(resolve, helpers.consts.WAIT_FOR_FINISH_POLL_INTERVAL),
+		);
+	}
 	return {
-		json: { ...run.data },
+		json: { ...lastRunData },
 	};
 }
 

nodes/Apify/resources/actors/run-actor/properties.ts

@@ -103,13 +103,9 @@ configuration for the Actor (typically \`latest\`).`,
 		displayName: 'Wait for Finish',
 		name: 'waitForFinish',
 		description:
-			"The maximum number of seconds the server waits for the run to finish. By default the server doesn't wait for the run to finish and returns immediately. The maximum value is 60 seconds.",
-		default: null,
-		type: 'number',
-		typeOptions: {
-			minValue: 0,
-			maxValue: 60,
-		},
+			'Whether to wait for the run to finish before continuing. If true, the node will wait for the run to complete (successfully or not) before moving to the next node. Note: The maximum time the workflow will wait is limited by the workflow timeout setting in your n8n configuration.',
+		default: true,
+		type: 'boolean',
 		displayOptions: {
 			show: {
 				resource: ['Actors'],