---

name: apify-hello-world description: | Run your first Apify Actor and retrieve results via apify-client. Use when starting a new Apify integration, testing connectivity, or learning the Actor call/dataset retrieval pattern. Trigger with "apify hello world", "apify example", "run an apify actor", "apify quick start", "first apify scrape". allowed-tools: Read, Write, Edit, Bash(npm:), Bash(npx:), Bash(node:*) version: 1.5.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• scraping
• automation
• apify compatibility: Designed for Claude Code

---

Apify Hello World

Overview

Run a public Actor from the Apify Store, wait for it to finish, and retrieve the scraped data. This demonstrates the fundamental call-wait-collect pattern used in every Apify integration.

Prerequisites

• npm install apify-client completed
• APIFY_TOKEN environment variable set
• See apify-install-auth if not ready

Authentication

Every call authenticates with a personal API token passed to the client constructor: new ApifyClient({ token: process.env.APIFY_TOKEN }). Keep the token in the APIFY_TOKEN environment variable — never hard-code it in the script. Full setup (where to generate the token, how to export it) lives in the apify-install-auth skill.

Core Pattern: Call Actor, Get Data

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

// 1. Run an Actor and wait for it to finish
const run = await client.actor('apify/website-content-crawler').call({
  startUrls: [{ url: 'https://docs.apify.com/academy' }],
  maxCrawlPages: 5,
});

// 2. Retrieve results from the default dataset
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(`Crawled ${items.length} pages:`);
items.forEach(item => {
  console.log(`  - ${item.url}: ${item.text?.substring(0, 80)}...`);
});

This is the whole workflow at a high level: authenticate, .call() an Actor, then read its default dataset. For sync-vs-async execution, pagination, downloads, key-value store retrieval, run-configuration options, and a table of popular starter Actors, see run & retrieval patterns.

Instructions

Step 1: Create the Script

Use Write (or Edit an existing file) to create hello-apify.ts (or .js) with the Core Pattern code above. Use Read to confirm the file contents before running.

Step 2: Run It

# With tsx (recommended)
npx tsx hello-apify.ts

# Or with Node.js (plain JS)
node hello-apify.js

Step 3: Understand the Output

The Actor runs on Apify's cloud infrastructure. See the Output section below for the run-object fields returned when it finishes.

Output

A successful run returns a run object plus a populated dataset. The fields you read most:

Field	Meaning
run.id	Unique run identifier
run.status	SUCCEEDED, FAILED, TIMED-OUT, or ABORTED
run.defaultDatasetId	ID of the dataset containing scrape results
run.defaultKeyValueStoreId	ID of the KV store with metadata/artifacts
run.statusMessage	Human-readable detail (essential when status is not SUCCEEDED)

client.dataset(run.defaultDatasetId).listItems() returns { items }, where each item is one scraped record (shape depends on the Actor). Always branch on run.status before reading the dataset — a FAILED run can leave an empty or partial dataset. See worked examples for the full run-object breakdown.

Error Handling

Error	Cause	Solution
Actor not found	Wrong Actor ID	Check ID at apify.com/store
run.status === 'FAILED'	Actor crashed	Check run.statusMessage for details
run.status === 'TIMED-OUT'	Exceeded timeout	Increase timeout or reduce workload
Dataset is empty	Actor produced no output	Verify input parameters; check Actor logs
402 Payment Required	Insufficient compute units — Apify returns HTTP 402 when your account is out of prepaid units	Top up at console.apify.com/billing

Examples

Minimal happy-path collection — call an Actor and count the results:

const run = await client.actor('apify/website-content-crawler').call({
  startUrls: [{ url: 'https://example.com' }],
  maxCrawlPages: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Scraped ${items.length} pages`);

For the complete status-guarded "scrape and save to JSON" script and a full breakdown of the run object, see worked examples.

Resources

• Apify Store — Browse Actors
• Run Actor via API
• JS Client Examples
• Run & retrieval patterns — sync/async, pagination, run config, starter Actors
• Worked examples — full scrape-and-save script

Next Steps

Once your first Actor run succeeds, proceed to the apify-local-dev-loop skill to build and iterate on your own Actor locally, then deploy it back to the Apify platform. That skill covers the develop-run-debug cycle in depth.