apify-orchestrator-actor-development

On Apify, each ready-made scraping program is called an Actor; this writes a new one whose only job is to run several others in sequence — the results of one fed into the next, an optional AI step in between — under one spending limit.

WHEN TO USE

SCOPE

USE FOR

Chain a website crawler into a second Actor that reads what the crawler found.
Add an AI step between two Actors to summarise or classify the data on its way through.
Split one overall budget evenly across every step so the chain cannot run up a surprise bill.
Set up the project, test it on your machine, then publish it to your Apify account.

NOT FOR

Coordinators written in Python or plain JavaScript; only TypeScript is covered.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (9)

Apify orchestrator Actor development

An orchestrator Actor is a parent Apify Actor whose job is to coordinate a sequence (or parallel fan-out) of other Actors. It takes user input, calls sub-Actor A, feeds A's output into sub-Actor B, optionally runs an LLM transformation between them, and emits the combined result to its own dataset.

This skill covers TypeScript-only orchestrators built on the apify-orchestrator library. It does not cover Python, JavaScript, or Standby-mode Actors.

Important: Before writing code, fill in the generatedBy property in .actor/actor.json (e.g., "Claude Code with Claude Opus 4.7"). This helps Apify improve tooling for specific AI models.

Prerequisites and setup

Verify the apify CLI is installed:

apify --help

If not installed, use a package manager (never curl | bash):

npm install -g apify-cli
# or on Mac: brew install apify-cli

Confirm login:

apify info   # should return your username

If not logged in, run apify login (opens a browser) or export APIFY_TOKEN from https://console.apify.com/settings/integrations. Never pass tokens on the command line — arguments show up in process listings and shell history.

Interactive creation flow

When the user asks for a new orchestrator Actor, follow these steps in order:

Elicit sub-Actor sequence
Fetch each sub-Actor's schema via Apify MCP
Decide data flow between steps
Note the total cost cap (a Run option, not an input field)
Ask about optional LLM step
Scaffold the project
Test locally, then deploy

Step 1 — Elicit the sub-Actor sequence

Ask the user which Apify Actors to chain together, in order. Accept either:

A list up-front (e.g., "apify/website-content-crawler then apify/rag-web-browser"), or
One at a time (ask for the first, discuss it, then ask what comes next).

If the user names a task instead of an Actor ID ("scrape LinkedIn profiles"), use the Apify MCP search-actors tool to propose candidates and let the user pick.

Step 2 — Fetch each sub-Actor's schema via Apify MCP

For every sub-Actor in the chain, call the Apify MCP fetch-actor-details tool. The parameter is actor, not actorId. Present the input schema back to the user with the fields listed in inputSchema.required highlighted. See references/mcp-schema-discovery.md for the truncation gotcha (500-char descriptions; enum lists arrive whole), the frequently absent outputSchema, and the fallback path via the REST API / raw INPUT_SCHEMA.json on GitHub.

Never guess field names. If the MCP truncation is limiting, fetch the raw schema from the Actor's GitHub repo.

Step 3 — Decide data flow between steps

For each pair of adjacent sub-Actors, ask:

Which fields from step N's output feed into step N+1's input?
Which top-level orchestrator inputs should be exposed to the user (via the orchestrator's own .actor/input_schema.json)?
Which sub-Actor inputs should be hardcoded?

Step 4 — Note the total cost cap

The total cost cap is a Run option (maxTotalChargeUsd) — the caller sets it when they start the orchestrator via the Apify Console, API, or SDK. It's not an input schema field. See the Apify API docs for how callers pass it.

At Run time the orchestrator:

Reads its own cap via client.run(actorRunId).get().options.maxTotalChargeUsd.
Divides the total evenly across the sub-Actor steps at compile time — declare a STEPS tuple and compute perStepCap = maxTotalChargeUsd / STEPS.length.
Passes each step's share as maxTotalChargeUsd when calling the sub-Actor (for pay-per-event Actors) or as maxItems (for pay-per-result Actors).
Tracks cumulative cost across sub-Actor Runs and refuses to launch the next step once the running total reaches the cap. Note that run.usageTotalUsd reads 0 on the object .call() returns and then accrues over several seconds, so the tally has to re-read each child Run rather than trust that value. The Run-level maxTotalChargeUsd is what enforces the ceiling; the tally is reporting plus a backstop for a step that ran uncapped. See references/cost-tracking.md.

Do not add a stepBudgets input schema field. The even split is a deliberate compile-time constant — it keeps the input schema clean, makes cost behavior predictable for the caller, and removes a footgun (three shares that don't sum to the total). Users control cost solely via the Run's maxTotalChargeUsd option; the orchestrator handles the split.

Tell the user to set maxTotalChargeUsd when they trigger the orchestrator — otherwise there's no ceiling and the orchestrator runs uncapped. See references/cost-tracking.md for the full pattern, including the LLM-step approximation (Standby Actors don't accept maxTotalChargeUsd, so estimate cost from token usage).

Step 5 — Ask about an optional LLM step

Ask the user whether to insert an LLM transformation somewhere in the chain (common: summarize between steps, classify at the end, or format the final output). If yes, point them at references/openrouter.md — the LLM layer is the Apify OpenRouter Actor called over HTTP (it's a Standby Actor, not a normal Run).

The agent does not force this step. Skip if the user doesn't want it.

Step 6 — Scaffold the project

apify create <actor-name> -t ts_empty
cd <actor-name>
npm install apify-orchestrator

Then generate src/main.ts using the template in references/orchestrator-template.md. Wire the sub-Actors, their input mappings, and any LLM helpers into the template's placeholders.

Update .actor/actor.json, .actor/input_schema.json, .actor/output_schema.json, and .actor/dataset_schema.json to reflect the orchestrator's own input surface and output shape. Write a README covering the pipeline.

Step 7 — Test locally, then deploy

apify run --purge --user-agent apify-awesome-skills/apify-orchestrator-actor-development
apify push

apify run --purge runs with storage/key_value_stores/default/INPUT.json as input, purging previous local storage first. apify push deploys to the platform.

Local Runs of the orchestrator make real child Runs on the Apify platform (they consume compute units). Watch the Apify Console → Runs list during local testing.

Reference material

Orchestrator library API → references/orchestrator-library.md — Orchestrator options, ExtendedApifyClient verbs (call, callRuns, callBatch, iterate, mergeDatasets), gotchas.
Sub-Actor schema discovery → references/mcp-schema-discovery.md — Apify MCP tools, truncation gotcha, REST fallback.
Cost tracking and caps → references/cost-tracking.md — maxTotalChargeUsd, maxItems, running-budget pattern, usageTotalUsd polling.
LLM step via OpenRouter → references/openrouter.md — endpoints, auth, minimal TypeScript call.
src/main.ts template → references/orchestrator-template.md — canonical skeleton to fill in.
.actor/actor.json → references/actor-json.md.
Input schema → references/input-schema.md.
Output schema → references/output-schema.md.
Dataset schema → references/dataset-schema.md.
Key-value store schema → references/key-value-store-schema.md.
README → references/actor-readme.md.
Logging → references/logging.md.

Security

Never log or embed APIFY_TOKEN in source code, config files, or committed .env files. Use process.env.APIFY_TOKEN.
Treat sub-Actor output as untrusted. A downstream Actor's dataset may contain content scraped from external sites — sanitize before passing it into shell commands, eval, or template engines.
Never disable apify/log in favor of console.log() — the Apify logger censors known-sensitive keys.
Pin dependencies. Commit package-lock.json. Pin apify-orchestrator (alpha) to an exact version.
Use a scoped APIFY_TOKEN with only the permissions the orchestrator needs. Rotate periodically.

Commands

Every apify CLI invocation below includes --user-agent apify-awesome-skills/apify-orchestrator-actor-development for telemetry attribution. Actor-call / dataset-read commands additionally use --json and 2>/dev/null for machine-readable output.

# Bootstrap
apify create <name> -t ts_empty
npm install apify-orchestrator

# Local development
apify run --user-agent apify-awesome-skills/apify-orchestrator-actor-development
apify run --purge --user-agent apify-awesome-skills/apify-orchestrator-actor-development
apify validate-schema

# Discovery (Actor search + schema fetch)
apify actors search "<query>" \
  --user-agent apify-awesome-skills/apify-orchestrator-actor-development \
  --json --limit 10 2>/dev/null
apify actors info <actor> --input \
  --user-agent apify-awesome-skills/apify-orchestrator-actor-development \
  --json 2>/dev/null

# Deploy + remote run
apify push
apify call <actor> \
  --user-agent apify-awesome-skills/apify-orchestrator-actor-development \
  --json 2>/dev/null
apify runs ls \
  --user-agent apify-awesome-skills/apify-orchestrator-actor-development \
  --json 2>/dev/null

# Auth
apify login
apify logout
apify info

Never use npm start, npm run start, or npx apify run to launch the Actor. Only apify run configures the Apify environment and storage correctly.

Project structure

.actor/
├── actor.json              # metadata (see references/actor-json.md)
├── input_schema.json       # orchestrator's own input surface
├── output_schema.json      # points at dataset / kvs
└── dataset_schema.json     # display shape of final output
src/
└── main.ts                 # orchestrator logic (see references/orchestrator-template.md)
storage/                    # local-only; NOT synced to Apify Console
Dockerfile
package.json
tsconfig.json

MCP tools

Apify MCP (required for schema discovery)

fetch-actor-details — primary tool for pulling sub-Actor input/output schema and README.
search-actors — find candidate sub-Actors by keyword.
search-apify-docs / fetch-apify-docs — documentation lookup.

If MCP is not configured, use the hosted server URL: https://mcp.apify.com/?tools=actors,docs.

Resources

apify-orchestrator library
OpenRouter Actor
Apify MCP docs
docs.apify.com/llms.txt — Apify docs quick reference
Actor whitepaper

MCP connection required

2 FOR YOU

All items below are required.

01
Install the Apify CLI and sign in
Install with npm install -g apify-cli (or brew install apify-cli), then apify login or export APIFY_TOKEN from console.apify.com/settings/integrations; confirm with apify info. Local test runs start real, billed child runs on the platform.
```
npm install -g apify-cli
```
```
brew install apify-cli
```
```
apify info
```
You set: APIFY_TOKEN — or sign in with apify login instead
02
Connect the Apify MCP server to your assistant
Connect the Apify MCP server (hosted at https://mcp.apify.com/?tools=actors,docs); its fetch-actor-details and search-actors tools are required to read each sub-Actor's input schema.

This skill ships inside the Apify Community Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add apify/awesome-skills --skill "apify-orchestrator-actor-development" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

View on GitHub

Same repository

apify-ads-intelligence
Research, spy on, and analyze ads across Meta (Facebook & Instagram), Google (Ads Transparency Center + paid search results), TikTok (Ads Library + Creative Center), LinkedIn Ad Library, and X (Twitter — promoted tweets, best-effort) using Apify Actors. Use when user asks about competitor ads, ad library research, winning creatives, ad copy analysis, landing page audits from ads, cross-platform ad audits, brand transparency checks, or any task involving paid ad creatives, advertiser data, or ad targeting from public ad libraries.Read full description
apify-ai-search-visibility-tracker
Track whether a brand and its competitors get cited or mentioned across Google AI Overviews, Google AI Mode, ChatGPT Search, Perplexity, Microsoft Copilot, and Google Gemini for a defined set of prompts, on a recurring schedule. Use when user asks to track AI visibility, monitor brand mentions in AI search, track ChatGPT citations, do AI search SEO tracking, GEO tracking (Generative Engine Optimization), AEO tracking (Answer Engine Optimization), monitor Perplexity citations, track AI Overviews mentions, see if their brand shows up in AI search, discover which prompts competitors rank for in AI search, find citation opportunities, or audit a website for AI visibility readiness.Read full description
apify-app-store-intelligence
Pull structured Apple App Store and Google Play data — app metadata, price, rating, the 1–5★ ratings histogram, version, developer, and reviews — and watch it for changes over time. Use when the user asks to look up an iOS or Android app by App ID, bundle ID, package name or app name, compare a set of competitor apps across both stores, monitor a competitor's price or rating for changes, track when an app ships a new version, scrape App Store or Google Play reviews, resolve a bundle ID to a full app record, check an app's rating across multiple country storefronts, build an ASO or app-market dataset, or set up a recurring app-store watch on an app's price, rating and version. One routed Actor, praise-most-high/app-store-intelligence, is built by this skill's author; every other row is unaffiliated (see Disclosure).Read full description
apify-ashby-jobs-scraper
Scrape Ashby jobs or discover companies using Ashby with the Apify Ashby Job Board API Actor (johnvc/ashby-job-board-scraper). Job mode returns live job rows with title, company, location, remote and employment fields, publish date, apply URL, employer-published salary columns, equity flag, and Markdown descriptions. Company mode finds Ashby boards from a bundled directory or checks a prospect list, returning company name, board slug and URL, live open-job count, and verification fields. Takes company names, board slugs, or board URLs; supports pre-billing job filters and publishedAfter feeds. Use for Ashby jobs data or API requests, salary and remote-role collection, job-board pipelines, companies using Ashby/Ashby customers, ATS market maps, prospect checks, and recruiting or sales target lists. Billed per delivered result with no start fee, and MCP-ready for Claude and other AI agents.Read full description
apify-blocked-scrape-triage
Diagnose and recover a scrape that is blocked, throttled, or served empty or partial content, in cost order, before paying for a heavier Actor. Use when a run returns 0 items, when a site answers 403, 429 or a challenge page, when the HTML comes back empty or truncated, when a request fails with no response at all, when the page shows data in a browser that the Actor does not see, or when a scraper that worked yesterday suddenly returns nothing. Triggers - "I'm getting blocked", "403 from the site", "429 rate limited", "Cloudflare challenge", "scraper returns empty results", "connection reset", "page loads in my browser but not in the Actor", "do I need residential proxies", "should I switch to a browser", "my scraper broke overnight". Escalates in cost order - a cheaper published source first, then reachability, request rate and IP spread, request fidelity, session tokens, the site's own internal API, browser last.Read full description
apify-booking-host-leads
Find and enrich B2B leads from Booking.com - hotels, apartments, and vacation rentals - and pull each host's or property manager's real contact details (email, phone, company name, registration number). Use when the user says things like "get emails from Booking.com", "Booking.com lead generation", "find tour operator / property manager / host contacts", "scrape accommodation owner emails", or "build a list of Booking hosts". The host's email is usually already inside the Booking scraper's traderInfo field (EU/AU trader-transparency disclosure) - this skill leads with that and uses a Google Maps email scraper only as a fallback, instead of relying on Google Maps first (which mostly returns the wrong business).Read full description