feat: 122 zapier add Get Actor Run by ID search

[daveomri]

---

What & why

Part of #121 (Zapier Agents compatibility). Adds a Get Actor Run by ID search, the building block for async agent orchestration: Run Actor/Task returns a run ID, and this search later checks its status/retrieves output. The existing Find Last Actor Run only returns the most recent run, which is fragile with multiple concurrent runs.

Verified locally: mocked suite green, live API tested via zapier-platform invoke. Not yet tested in Zapier UI - blocked on push access (collaborator to admin request pending).

Changes

• src/searches/get_run.js - GET /v2/actor-runs/{runId} via wrapRequestWithRetries; 404 → [] (miss = success, existing 'not found' convention); else enrichActorRun(...) → [run] (inlined dataset items, KV OUTPUT, detailsPageUrl). Reuses ACTOR_RUN_SAMPLE + ACTOR_RUN_OUTPUT_FIELDS so output stays chainable (raw id, defaultDatasetId, etc. preserved).
• src/output_fields.js - new getRunDatasetOutputFields: derives dynamic dataset columns from the run's own defaultDatasetId. The actor-based helper couldn't, since this search takes only runId (not actorId).
• index.js - registered.
• test/searches/get_run.js - 3 tests: found case, 404 → [], dynamic output fields.

Action metadata

Field	Value
key	getActorRunById
noun / label	Actor Run / Get Actor Run by ID
description	Retrieves details and results of a specific Actor run by its ID. Use to check status or fetch output of a run started in a previous step (via Run Actor or Run Task).

Input: runId (required, string; example ID in helpText).

Testing

• Mocked: 63 passing / 8 pending / 0 failing. Lint clean. validate --without-style sound.
• Live: existing run → enriched [run], missing run → [].
• Pre-existing E2E failures (shape drift, token-scope) unrelated.

Notes

No renamed keys, no auth changes, no version/CHANGELOG edits. Targets epic branch.

[Copilot]

Pull request overview

Adds a new Zapier Search action to retrieve and enrich an Apify Actor run by run ID, enabling more reliable async orchestration (e.g., “Run Actor/Task” → later “Get Actor Run by ID” to check status and fetch output) instead of relying on “last run” semantics.

Changes:

• Introduces getActorRunById search (GET /v2/actor-runs/{runId}) and enriches the run with dataset items, KV OUTPUT, and a console details URL.
• Adds a new dynamic output-fields helper that derives dataset fields from the run’s defaultDatasetId.
• Registers the new search in index.js and adds mocked/E2E-capable tests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/searches/get_run.js	Implements the new “Get Actor Run by ID” search and run enrichment.
src/output_fields.js	Adds getRunDatasetOutputFields to generate dynamic dataset item output fields based on runId.
index.js	Registers the new search in the app’s searches map.
test/searches/get_run.js	Adds tests for found/missing runs and dynamic output-fields behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.