Apify Deploy Integration
Overview
Deploy Actors to the Apify platform and integrate their results into external
applications. Covers apify push deployment, API-triggered runs from web apps
(synchronous and async patterns), webhook receivers, scheduled scraping pipelines,
and container deployment.
SKILL.md gives you the workflow and the core skeleton. Complete, copy-paste code
for every pattern lives in references/implementation.md;
end-to-end worked scenarios are in references/examples.md.
Prerequisites
- Actor tested locally (
apify run)
apify login completed (stores CLI credentials)- Target application ready for integration
Authentication
Apps authenticate with an Apify API token. Generate one in Apify Console →
Settings → Integrations and expose it as the APIFY_TOKEN environment variable —
never hard-code it. The apify CLI uses its own credentials from apify login,
separate from APIFY_TOKEN. Full auth notes: references/implementation.md.
Instructions
Step 1: Deploy the Actor to the platform
apify push
apify push username/my-scraper
apify pull username/existing-actor
Step 2: Trigger the Actor from your app
Instantiate ApifyClient with your token, then either call() (blocks until the
run finishes) or start() (returns immediately for polling). Here is the core
synchronous skeleton:
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('username/product-scraper').call({
startUrls: [{ url: 'https://store.example.com' }],
maxItems: 500,
});
if (run.status !== 'SUCCEEDED') throw new Error(run.statusMessage);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
The full typed service — scrapeProducts (blocking), startScrape +
getScrapeResults (async poll) — is in
references/implementation.md.
Step 3: Choose an integration pattern
Pick the pattern that matches your app, then copy the full handler from the
reference:
- Next.js API route — start a run in a
POST, poll by run ID in a GET. Avoids
serverless timeouts. See implementation.md.
- Express webhook receiver — register an Apify webhook and react on
ACTOR.RUN.SUCCEEDED / FAILED / TIMED_OUT. See implementation.md.
- Scheduled pipeline — run on cron/Apify Schedule, export CSV, archive to a
named dataset. See implementation.md.
- Docker / Cloud Run — containerize an app that calls Apify, inject the token
as a secret. See implementation.md.
Rule of thumb: poll for request/response UX (a user waits on a result); use
webhooks for fire-and-forget pipelines (scheduled scrapes, background enrichment).
Output
- A deployed Actor on the Apify platform (
apify push build succeeds)
- An integration module (
src/services/apify.ts) exposing blocking + async calls
- API routes / webhook receivers wired into your app's framework
- Structured results read from the Actor's default dataset (JSON or CSV export)
- Optional date-stamped archive in a named dataset for historical access
Error Handling
| Issue | Cause | Solution |
|---|
apify push fails | Auth or build error | Check apify login and Dockerfile |
| Webhook not received | URL unreachable from internet | Use ngrok for dev; verify HTTPS in prod |
| Timeout in API route | Actor takes too long | Use async pattern (start + poll) |
| Memory error on platform | Actor needs more RAM | Increase memory option |
| Large dataset download | >100MB results | Use pagination or streaming |
Examples
Three end-to-end scenarios — synchronous script call, non-blocking Next.js API,
and a scheduled CSV-export pipeline — are worked through in
references/examples.md. Minimal blocking call:
import { scrapeProducts } from './services/apify';
const products = await scrapeProducts(['https://store.example.com/p/1']);
console.log(`Got ${products.length} products`);
Resources
Next Steps
For webhook event handling in depth, see the apify-webhooks-events skill. For the
full integration code referenced above, see
references/implementation.md.
