OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add apify/agent-skills --skill apify-sdk-integration
Integrate Apify into an existing JavaScript/TypeScript or Python application using the apify-client package. Use when adding web scraping, automation, or data extraction capabilities to an existing app via the Apify API.
npx skills add apify/agent-skills --skill apify-sdk-integration
Add Apify Actor execution to an existing application. This skill covers the apify-client package for JS/TS and Python, plus the REST API for other languages.
apify-clientis the API client for calling Actors from your app.apifyis the SDK for building Actors (wrong package for this use case).Always install
apify-client. Never installapifyfor integration work.
The user needs an APIFY_TOKEN. Direct them to Console > Settings > Integrations at https://console.apify.com/settings/integrations to create one. If they don't have an account: https://console.apify.com/sign-up (free, no credit card).
Store the token securely — environment variable or secrets manager, never hardcoded.
Before writing integration code, find the Actor that fits the user's needs. Use the MCP tools if available:
search-actors — search the Apify Store by keywordfetch-actor-details — get the Actor's input schema, output format, and pricingAlternatively, browse https://apify.com/store. Append .md to any Actor's Store URL to get its docs in markdown.
.call() blocks until the Actor finishes. Use for short-running Actors (under a few minutes).
Use .start() + .waitForFinish() for long-running Actors or when you need the run ID immediately.
For languages without an official client, use the REST API directly.
Full API reference: https://docs.apify.com/api/v2
timeoutSecs in the Actor input or use waitSecs on .call() to avoid indefinite waits.limit and offset when retrieving dataset items. Default limit is 250K items.ApifyClient instance and reuse it across calls.fetch-actor-details MCP tool or append .md to the Actor's Store URL to get the schema before constructing input.If the Apify MCP server is available, use search-apify-docs and fetch-apify-docs tools for contextual documentation lookups during development.
const run = await client.actor('apify/web-scraper').start({
startUrls: [{ url: 'https://example.com' }],
});
// Poll for completion
const finishedRun = await client.run(run.id).waitForFinish();
// Retrieve results
const { items } = await client.dataset(finishedRun.defaultDatasetId).listItems();// Dataset items (structured data from pushData)
const { items } = await client.dataset(run.defaultDatasetId).listItems({
limit: 100,
offset: 0,
});
// Key-value store (files, screenshots, etc.)
const record = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');try {
const run = await client.actor('apify/web-scraper').call(input);
if (run.status !== 'SUCCEEDED') {
const log = await client.log(run.id).get();
throw new Error(`Actor failed with status ${run.status}: ${log}`);
}
const { items } = await client.dataset(run.defaultDatasetId).listItems();
} catch (error) {
if (error.message?.includes('not found')) {
// Actor ID is wrong or Actor was deleted
} else if (error.statusCode === 401) {
// Invalid or missing APIFY_TOKEN
}
throw error;
}pip install apify-clientfrom apify_client import ApifyClient
import os
client = ApifyClient(token=os.environ['APIFY_TOKEN'])
run = client.actor('apify/web-scraper').call(run_input={
'startUrls': [{'url': 'https://example.com'}],
'maxPagesPerCrawl': 10,
})
items = client.dataset(run['defaultDatasetId']).list_items().itemsrun = client.actor('apify/web-scraper').start(run_input={
'startUrls': [{'url': 'https://example.com'}],
})
# Poll for completion
finished_run = client.run(run['id']).wait_for_finish()
items = client.dataset(finished_run['defaultDatasetId']).list_items().itemsfrom apify_client import ApifyClientAsync
client = ApifyClientAsync(token=os.environ['APIFY_TOKEN'])
run = await client.actor('apify/web-scraper').call(run_input={
'startUrls': [{'url': 'https://example.com'}],
})
items = (await client.dataset(run['defaultDatasetId']).list_items()).itemsPOST https://api.apify.com/v2/actors/{actorId}/runs
Authorization: Bearer <APIFY_TOKEN>
Content-Type: application/json
{ "startUrls": [{ "url": "https://example.com" }] }GET https://api.apify.com/v2/actor-runs/{runId}
Authorization: Bearer <APIFY_TOKEN>GET https://api.apify.com/v2/datasets/{datasetId}/items?format=json
Authorization: Bearer <APIFY_TOKEN>