Apify — actor-run/getActorRuns

When to Use

Actor health monitoring: Run on a schedule to detect if a specific actor has accumulated failed runs. Filter by status: "FAILED" and alert if count exceeds a threshold, indicating a systematic scraping problem.
Run history auditing: Build a compliance report showing all runs of a given actor over a time period. Use pagination (Offset and Limit) inside a Loop to accumulate all historical run records.
Detecting stuck runs: Filter by status: "RUNNING" and check if any run's startedAt timestamp is older than a maximum expected duration, then trigger an alert for stalled actor runs.
Cost tracking per actor: Retrieve the most recent N runs for each actor and fetch per-run costs via actor-run/get to build a per-actor cost breakdown report.
Dataset enumeration: When you need the dataset IDs for multiple recent successful runs of an actor (for differential comparison or batch processing), use this node with status: "SUCCEEDED" to get a list of run IDs, then fetch each run's details.

Pagination: Results are ordered by run start time descending by default (Desc: true). Use Offset and Limit to page through results. The count output field reflects the number of runs returned in this page — compare with Limit to determine if more pages exist. Note that count is the page count, not the total run count across all pages.

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-run"`.
`operation`	Required	Must be `"get-actor-runs"`.
`actorId`	Required	The actor whose run history to retrieve. Accepts `username~actor-name` or raw actor ID.
`status`	Optional	Filter runs by status. Accepted values: `READY`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TIMED-OUT`, `ABORTING`, `ABORTED`. Omit to return runs of all statuses.
`offset`	Optional	Number of runs to skip for pagination. Default `0`. Must be non-negative.
`limit`	Optional	Maximum number of runs to return per page. Default `50`. Valid range: 1–10000.
`desc`	Optional	Sort order. `"true"` (default) = newest runs first. `"false"` = oldest runs first.

Sample Configuration

{
  "resource": "actor-run",
  "operation": "get-actor-runs",
  "credentialId": "apify-prod-token",
  "actorId": "apify~web-scraper",
  "status": "FAILED",
  "offset": "0",
  "limit": "20",
  "desc": "true"
}

Validation Errors

Error	Cause
`API token is required`	`credentialId` / `apiToken` is missing or empty.
`Actor ID is required`	`actorId` is missing or empty.
`Invalid settings for actor-run/get-actor-runs`	Internal type mismatch. Verify `resource` is `"actor-run"` and `operation` is `"get-actor-runs"`.
`APIFY_ERROR` (error port)	Actor ID not found, API token lacks permission to view runs, or a network error occurred.

Output

Success Port

Field	Type	Description
`actorId`	string	The actor whose runs are listed.
`runs`	array	Array of run summary objects. Each contains `runId`, `status`, `startedAt`, and `finishedAt`.
`count`	number	Number of runs in this response page.
`offset`	number	Offset used for this request, echoed from configuration.
`limit`	number	Limit used for this request, echoed from configuration.

Run summary object fields:

Field	Type	Description
`runId`	string	Unique run identifier.
`status`	string	Run status at time of query.
`startedAt`	string	ISO 8601 start timestamp. Empty if not yet started.
`finishedAt`	string	ISO 8601 finish timestamp. Empty if still in progress.

Error Port

Routes here when the actor ID is not found, the API token lacks permission, or a network error occurs. Output contains errorCode ("APIFY_ERROR") and message.

Sample Output

{
  "actorId": "moJRLRc85AitArpNN",
  "runs": [
    {
      "runId": "run_abc111",
      "status": "FAILED",
      "startedAt": "2026-05-26T08:00:01.000Z",
      "finishedAt": "2026-05-26T08:00:45.000Z"
    },
    {
      "runId": "run_abc110",
      "status": "FAILED",
      "startedAt": "2026-05-25T08:00:01.000Z",
      "finishedAt": "2026-05-25T08:01:03.000Z"
    }
  ],
  "count": 2,
  "offset": 0,
  "limit": 20
}

Expression Reference

Expression	Returns
`{{ $output.apify.runs }}`	Array of run summary objects.
`{{ $output.apify.count }}`	Number of runs in this page.
`{{ $output.apify.runs[0].runId }}`	Most recent run ID (with `desc: true`).
`{{ $output.apify.runs[0].status }}`	Status of the most recent run.
`{{ $output.apify.actorId }}`	Actor ID echoed from configuration.

Node Policies & GuardRails

Policy	Recommendation	Severity
API token storage	Use `credentialId`; never embed raw tokens.	Critical
Pagination completeness	When building complete run histories, implement pagination in a `Loop` node. Stop when `count` is less than `limit`. Fetching only page 1 misses older runs for high-volume actors.	High
Status filter specificity	Always apply a `status` filter in production to reduce response size and improve clarity. Fetching all statuses is only appropriate for general audit reports.	Medium
Limit cap	Set `limit` to 50–100 for interactive/monitoring workflows. Large limits (1000+) produce large payloads and slow downstream processing.	Medium
Run detail fetching	This node returns a summary view. For per-run cost data, dataset IDs, or exit codes, call `actor-run/get` for each `runId` in the returned `runs` array.	Medium

Examples

Monitor Failed Runs — Alert If Failures Detected

{
  "resource": "actor-run",
  "operation": "get-actor-runs",
  "credentialId": "apify-prod-token",
  "actorId": "my-org~price-monitor",
  "status": "FAILED",
  "offset": "0",
  "limit": "10",
  "desc": "true"
}

Run hourly. An IfCondition checks {{ $output.apify.count }} > 0. If failures exist in the last 10 runs, a Slack notification lists the runId and finishedAt values from the runs array for ops investigation.

Retrieve All Successful Runs for Batch Processing

// Loop node (max 20 iterations, variable: currentOffset starts at 0)
{
  "resource": "actor-run",
  "operation": "get-actor-runs",
  "credentialId": "apify-prod-token",
  "actorId": "apify~web-scraper",
  "status": "SUCCEEDED",
  "offset": "{{ $variables.currentOffset }}",
  "limit": "50",
  "desc": "false"
}
// After each iteration: currentOffset += 50
// Break when count < 50

Paginates through all successful runs of an actor in chronological order, accumulating run IDs in a variable array. Used by a batch processing workflow that needs to re-process datasets from all successful runs since last month.

Actor Run History Dashboard

{
  "resource": "actor-run",
  "operation": "get-actor-runs",
  "credentialId": "apify-prod-token",
  "actorId": "{{ $input.actorId }}",
  "offset": "{{ $input.page * 25 }}",
  "limit": "25",
  "desc": "true"
}

Backs a user-facing run history dashboard. The actor ID and page number come from form inputs. Returns 25 runs per page in reverse chronological order for display in a BizFirstAI form table component.