Apify — actor-task/runAndGetDatasetItems

When to Use

Scheduled ETL pipelines: A cron-triggered BizFirstAI workflow runs a preconfigured product scraping task every night and loads the result directly into a data warehouse table without any intermediate state management or polling complexity.
Team-owned data pipelines: Data engineers configure and version Actor Tasks in Apify (proxies, selectors, output schema, memory); BizFirstAI workflow developers consume the output via a single node that only requires the Task ID.
Repeatable market intelligence: Run a saved competitor analysis task on demand or on schedule and immediately process the returned items for pricing decisions, trend detection, or reporting — no separate dataset fetch step required.
Webhook-triggered scraping: When a downstream system signals that new data is available at a source URL, trigger the relevant Actor Task and return its items in the same webhook processing workflow.
Parameterized daily reports: Combine UseCustomBody: true with dynamic date injection to run the same task with different date ranges each day and return the filtered dataset rows directly for reporting.

When to use Task vs Actor variant: Use actor-task/runAndGetDatasetItems when you have a saved Actor Task configured in Apify. Use actor/runAndGetDatasetItems when you need to configure the actor dynamically from workflow data, or when no task exists yet. Tasks are preferable for production pipelines because they isolate actor configuration from workflow configuration.

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-and-get-dataset-items"`.
`actorTaskId`	Required	The Actor Task to run. Format: `username~task-name` or raw task ID. Find task IDs in Apify Console → Actor Tasks.
`useCustomBody`	Optional	`"true"` to replace the task's stored input with `customBody`. Default `"false"`.
`customBody`	Optional	JSON string overriding the task's input. Applied only when `useCustomBody` is `"true"`.
`timeout`	Optional	Actor run timeout override in seconds (1–86400).
`memory`	Optional	Memory override in MB. Valid: `128`, `256`, `512`, `1024`, `2048`, `4096`, `8192`, `16384`, `32768`.
`build`	Optional	Actor build tag override.
`datasetOffset`	Optional	Number of dataset items to skip. Default `0`.
`datasetLimit`	Optional	Maximum items to return from the dataset. Default `50`. Valid range: 1–10000.
`datasetFields`	Optional	Comma-separated field names to include. Omit to return all fields.
`datasetOmit`	Optional	Comma-separated field names to exclude from each item.

Sample Configuration

{
  "resource": "actor-task",
  "operation": "run-and-get-dataset-items",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~weekly-lead-enrichment",
  "useCustomBody": "false",
  "timeout": "900",
  "memory": "2048",
  "datasetOffset": "0",
  "datasetLimit": "200",
  "datasetFields": "company,domain,contactEmail,linkedinUrl,employeeCount",
  "datasetOmit": ""
}

Validation Errors

Error	Cause
`API token and Task ID are required`	`credentialId` or `actorTaskId` is missing or empty.
`Invalid settings`	Internal type mismatch. Verify `resource` is `"actor-task"` and `operation` is `"run-and-get-dataset-items"`.
`APIFY_ERROR` (error port)	Task ID not found, actor run failed or timed out, or dataset retrieval failed after the run.

Output

Success Port

Field	Type	Description
`items`	array	Array of dataset item objects returned by the actor task. Fields match the actor's output schema, filtered by `datasetFields` / `datasetOmit`.
`itemCount`	number	Number of items in the `items` array. May be less than `datasetLimit` if the dataset has fewer items.

Error Port

Routes here when the task run fails, times out, the task ID is not found, or the dataset retrieval fails after a successful run. Output contains errorCode ("APIFY_ERROR") and message.

Sample Output

{
  "items": [
    {
      "company": "Acme Corporation",
      "domain": "acme.com",
      "contactEmail": "sales@acme.com",
      "linkedinUrl": "https://linkedin.com/company/acme",
      "employeeCount": 340
    },
    {
      "company": "TechStart Inc.",
      "domain": "techstart.io",
      "contactEmail": "hello@techstart.io",
      "linkedinUrl": "https://linkedin.com/company/techstart",
      "employeeCount": 42
    }
  ],
  "itemCount": 2
}

Expression Reference

Expression	Returns
`{{ $output.apify.items }}`	Full array of dataset items from the task run.
`{{ $output.apify.itemCount }}`	Total items returned in this response.
`{{ $output.apify.items[0].company }}`	First item's company field (field name depends on actor schema).
`{{ $output.apify.items[0].domain }}`	Domain field of the first result.

Node Policies & GuardRails

Policy	Recommendation	Severity
API token storage	Use `credentialId`; never embed raw tokens.	Critical
Timeout required	Always set `timeout` for task runs. Tasks can have long internal timeouts — cap the BizFirstAI wait to protect workflow execution time.	Critical
Dataset volume cap	Set `datasetLimit` to avoid loading excessively large datasets into workflow memory. For large volumes, use `actor-task/run` followed by paginated `dataset/getItems` calls.	High
Field projection	Use `datasetFields` to return only needed fields. Reduces payload size and speeds up data mapping in downstream nodes.	Medium
Custom body validation	When `useCustomBody` is true, validate the JSON structure before the run. An invalid JSON body causes the underlying actor to fail — not a configuration validation error.	Medium
Task versioning	Track task IDs in version-controlled configuration. When Apify task settings change, document the change and verify downstream field mapping remains compatible.	Medium

Examples

Nightly Lead Enrichment Pipeline

{
  "resource": "actor-task",
  "operation": "run-and-get-dataset-items",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~nightly-lead-scrape",
  "useCustomBody": "false",
  "timeout": "1800",
  "memory": "2048",
  "datasetLimit": "500",
  "datasetFields": "company,domain,contactEmail,jobTitle,location"
}

Runs nightly at 2 AM via a BizFirstAI scheduled trigger. The task handles proxy rotation and anti-bot measures internally. The workflow receives up to 500 enriched lead records and immediately upserts them into a CRM via a subsequent Salesforce node.

Daily Competitive Price Monitoring with Date Override

{
  "resource": "actor-task",
  "operation": "run-and-get-dataset-items",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~competitor-price-check",
  "useCustomBody": "true",
  "customBody": "{\"date\":\"{{ $now | date('YYYY-MM-DD') }}\",\"categories\":[\"laptops\",\"monitors\",\"keyboards\"]}",
  "timeout": "600",
  "memory": "1024",
  "datasetLimit": "300",
  "datasetFields": "sku,productName,price,currency,inStock,url"
}

The task's stored configuration handles the scraping logic; the BizFirstAI workflow injects today's date and target categories dynamically. Results feed a price comparison engine that triggers alerts when competitor prices drop below a threshold.

On-Demand Market Research

{
  "resource": "actor-task",
  "operation": "run-and-get-dataset-items",
  "credentialId": "apify-prod-token",
  "actorTaskId": "my-org~market-research-task",
  "useCustomBody": "true",
  "customBody": "{{ $output.researchConfig.serializedInput }}",
  "timeout": "300",
  "memory": "1024",
  "datasetLimit": "100",
  "datasetFields": "source,headline,url,publishedAt,sentiment"
}

Triggered via a form submission where analysts configure research parameters. The upstream node serializes the form values into a JSON string passed as customBody. The node returns news articles with sentiment scores for immediate review in the workflow's output form.