Apify — actor-task/run

When to Use

Stable scheduled pipelines: Configure a daily news scraping Actor Task in the Apify console (actor, URLs, output format, memory all preconfigured), then trigger it from BizFirstAI with nothing more than the Task ID — no actor configuration changes required in the workflow.
Team-managed actor configurations: Data engineers manage actor parameters in Apify; BizFirstAI workflow developers trigger tasks without needing to understand actor internals. Clean separation of concerns.
Parameterized task runs: Use UseCustomBody: true to override the task's stored input at runtime (e.g. inject today's date range or a list of target URLs from a previous workflow step) while keeping all other task settings unchanged.
Multi-environment task management: Maintain separate Apify tasks for development and production (with different proxy configurations, URL lists, or memory limits). Switch between them by changing only the ActorTaskId in the BizFirstAI workflow.
Compliance and auditability: Actor Tasks create a named, versioned run history in Apify that is separate from ad-hoc actor runs. Use tasks when you need auditable, named job executions for reporting purposes.

Actor Tasks vs Direct Actor Runs: Use actor-task/run when the actor configuration is stable and managed in Apify. Use actor/run when you need to dynamically configure actor parameters from workflow data or when no task has been set up. Tasks are especially valuable when multiple workflows share the same actor configuration — update the task once in Apify and all workflows pick up the change.

Configuration

Connection

Field	Required	Description
`credentialId`	Required	BizFirstAI credential ID holding the Apify API token.
`baseUrl`	Optional	Apify API base URL. Defaults to `https://api.apify.com`.

Operation

Field (config key)	Required	Description
`resource`	Required	Must be `"actor-task"`.
`operation`	Required	Must be `"run"`.
`actorTaskId`	Required	The Apify Actor Task to run. Format: `username~task-name` or a raw task ID string. Find task IDs in Apify Console → Actor Tasks.
`useCustomBody`	Optional	`"true"` to override the task's stored input with the value in `customBody`. Default `"false"` — runs the task with its stored input unchanged.
`customBody`	Optional	JSON string to use as the actor input, replacing the task's stored input. Only applied when `useCustomBody` is `"true"`. Ignored otherwise.
`timeout`	Optional	Override the task's stored timeout. Valid range: 1–86400 seconds.
`memory`	Optional	Override the task's stored memory in MB. Valid: `128`, `256`, `512`, `1024`, `2048`, `4096`, `8192`, `16384`, `32768`.
`build`	Optional	Override the task's stored actor build tag.

Sample Configuration

{
  "resource": "actor-task",
  "operation": "run",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~daily-product-scrape",
  "useCustomBody": "false",
  "timeout": "600",
  "memory": "1024"
}

Validation Errors

Error	Cause
`API token is required`	`credentialId` / `apiToken` is missing or empty.
`Task ID is required`	`actorTaskId` is missing or empty.
`Invalid settings for actor-task/run`	Internal type mismatch. Verify `resource` is `"actor-task"` and `operation` is `"run"`.
`APIFY_ERROR` (error port)	Task ID not found, API token lacks permission to run this task, or the underlying actor run fails.

Output

Success Port

Field	Type	Description
`runId`	string	Unique identifier for this task run. Use with `actor-run/get` to poll status.
`actorTaskId`	string	The Actor Task that was executed.
`runStatus`	string	Run status at response time: `READY`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TIMED-OUT`, `ABORTING`, or `ABORTED`.
`startedAt`	string	ISO 8601 timestamp when the run started.
`finishedAt`	string	ISO 8601 timestamp when the run finished. Empty string if still in progress.
`defaultDatasetId`	string	Default dataset ID for this run's output.
`defaultKeyValueStoreId`	string	Default key-value store ID for this run.
`defaultRequestQueueId`	string	Default request queue ID for this run.
`usageTotalUsd`	number	Total compute cost in USD at response time.
`exitCode`	number	Actor exit code. `0` = success, `-1` if not finished.

Error Port

Routes here when the task ID is not found, the API token lacks permission to run the task, or the underlying actor fails immediately. Output contains errorCode ("APIFY_ERROR"), message, and operation ("run").

Sample Output

{
  "runId": "run_t1a2s3k4r5u6",
  "actorTaskId": "my-org~daily-product-scrape",
  "runStatus": "RUNNING",
  "startedAt": "2026-05-26T08:00:01.000Z",
  "finishedAt": "",
  "defaultDatasetId": "ds_p7q8r9s0t1u2",
  "defaultKeyValueStoreId": "kvs_v3w4x5y6z7a8",
  "defaultRequestQueueId": "rq_b9c0d1e2f3g4",
  "usageTotalUsd": 0.0008,
  "exitCode": -1
}

Expression Reference

Expression	Returns
`{{ $output.apify.runId }}`	Run ID for polling with `actor-run/get`.
`{{ $output.apify.actorTaskId }}`	Task ID that was executed.
`{{ $output.apify.runStatus }}`	Current or final run status.
`{{ $output.apify.defaultDatasetId }}`	Dataset ID for retrieving output items.
`{{ $output.apify.usageTotalUsd }}`	Compute cost for cost tracking and alerting.

Node Policies & GuardRails

Policy	Recommendation	Severity
API token storage	Use `credentialId`; never embed raw tokens in workflow configuration.	Critical
Task ID environment separation	Maintain separate task IDs per environment (dev/staging/prod). Use a workflow environment variable to switch task IDs between deployments.	High
Custom body guard	Only set `useCustomBody: "true"` when you explicitly need to override the task input. Accidental custom body injection with an empty or malformed JSON will cause the actor to fail.	High
Override governance	Prefer letting the task control its own `timeout`, `memory`, and `build`. Override at the BizFirstAI node level only for exceptional cases (e.g. reduced timeout for a slow-day budget window).	Medium
Error port handling	Connect the error port. Task runs may fail due to actor errors, quota limits, or Apify platform incidents — handle gracefully.	Medium

Examples

Daily Scheduled Data Pipeline — No Custom Input

{
  "resource": "actor-task",
  "operation": "run",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~morning-product-feed",
  "useCustomBody": "false"
}

Runs a preconfigured product feed scraping task every morning at 6 AM via a BizFirstAI scheduled trigger. All actor configuration lives in Apify — the workflow only needs the Task ID and a credential reference.

Parameterized Run — Override Task Input at Runtime

{
  "resource": "actor-task",
  "operation": "run",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~google-search-task",
  "useCustomBody": "true",
  "customBody": "{\"queries\":[\"{{ $input.searchKeyword }}\"],\"maxPagesPerQuery\":2}",
  "timeout": "180"
}

The base task is configured with default proxy settings, output format, and actor build. The BizFirstAI node overrides only the search query at runtime based on workflow input. This pattern keeps actor management in Apify while allowing dynamic parameterization from the workflow.

Multi-Task Dispatcher via Loop

{
  "resource": "actor-task",
  "operation": "run",
  "credentialId": "apify-prod-token",
  "actorTaskId": "{{ $output.taskLoop.currentTaskId }}",
  "useCustomBody": "false",
  "memory": "512"
}

Inside a Loop iterating over an array of task IDs, this node triggers each task sequentially and collects their run IDs for downstream status checking. Memory is capped at 512 MB for all tasks in the batch to control costs during bulk runs.