apify
apify is the official SDK for building Apify Actors in JavaScript and TypeScript. It handles the Actor lifecycle, storage access, platform events, proxy configuration, and more.
Quick Start
This short tutorial will set you up to start using Apify SDK in a minute or two. If you want to learn more, proceed to the Apify Platform guide that will take you step by step through running your Actor on Apify's platform.
Apify SDK requires Node.js 16 or later. Add Apify SDK to any Node.js project by running:
npm install apify
To initialize your Actor and to stop it use the Actor.init() and Actor.exit() functions. You also may use Actor.main() function for cases with multiple crawlers in one context.
import { Actor } from 'apify';
await Actor.init();
const input = await Actor.getInput();
await Actor.setValue('OUTPUT', {
message: 'Hello from Apify SDK!',
input,
});
await Actor.exit();
You can also install the
crawleemodule, as it now provides the crawlers that were previously exported by Apify SDK. If you don't plan to use crawlers in your Actors, then you don't need to install it. Keep in mind that neitherplaywrightnorpuppeteerare bundled withcrawleein order to reduce install size and allow greater flexibility. That's why we manually install it with NPM. You can choose one, both, or neither. For more information and example please checkdocumentation.
What are Actors?
Actors are serverless programs that can do almost anything. From simple scripts and web scrapers to complex automation workflows, AI agents, or even always-on services that expose HTTP endpoints.
They can run either locally or on the Apify platform, where you can scale their execution, monitor runs, schedule tasks, integrate them with other services, or even publish and monetize them. If you're new to Apify, learn more about the platform in the Apify documentation.
For more context, read the Actor whitepaper.
What you can build
Almost any Node.js project can become an Actor, including projects for:
- Web scraping and crawling - The SDK works seamlessly with Crawlee, which makes Apify a natural place to deploy and scale your crawlers. Start from a ready-made Cheerio template.
- Browser automation - Drive a real browser with Playwright, Puppeteer, or Selenium to automate tasks, fill in forms, or test web apps.
- AI agents - Host agents built with your framework of choice. Ready-made Actor templates cover LangChain, LangGraph, BeeAI, and Mastra.
- MCP servers - Deploy an MCP server as an Actor and make its tools available to any MCP client. See the MCP server and MCP proxy templates.
- Web servers and APIs - Run a web server inside an Actor to serve HTTP requests, for example to expose your scraper as a live API. See the Standby templates.
Whatever you build, the Apify SDK doesn't lock you into a particular framework. Bring the libraries you already use, and let Apify run your project in the cloud.
Support
If you find any bug or issue with the Apify SDK, please submit an issue on GitHub. For questions, you can ask on Stack Overflow or contact support@apify.com
Upgrading
Visit the Upgrading Guide to find out what changes you might want to make, and, if you encounter any issues, join our Discord server for help!
Contributing
Your code contributions are welcome, and you'll be praised to eternity! If you have any ideas for improvements, either submit an issue or create a pull request. For contribution guidelines and the code of conduct, see CONTRIBUTING.md.
License
This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details.
Acknowledgments
Many thanks to Chema Balsas for giving up the apify package name
on NPM and renaming his project to jsdocify.
Index
Result Stores
Scaling
Sources
Other
- LogLevel
- Actor
- ActorInputError
- ApifyClient
- ApifyFileSystemStorageBackend
- ApifyStorageBackend
- ArgumentValidationError
- ChargingManager
- Configuration
- Log
- Logger
- LoggerJson
- LoggerText
- PlatformEventManager
- AbortOptions
- ActorPricingInfo
- ActorRun
- ApifyClientOptions
- ApifyEnv
- ApifyFileSystemStorageOptions
- ApifyStorageBackendOptions
- CallOptions
- CallTaskOptions
- ChargeOptions
- ChargeResult
- DatasetConsumer
- DatasetContent
- DatasetDataOptions
- DatasetIteratorOptions
- DatasetMapper
- DatasetReducer
- ExitOptions
- GlobInput
- InitOptions
- KeyConsumer
- KeyValueStoreIteratorOptions
- LoggerOptions
- MainOptions
- MetamorphOptions
- OpenStorageOptions
- ProxyConfigurationOptions
- ProxyInfo
- PseudoUrlInput
- QueueOperationInfo
- RebootOptions
- RecordOptions
- RequestQueueOperationOptions
- SetStatusMessageOptions
- StartOptions
- StorageAlias
- StorageId
- StorageName
- Timeout
- Token
- UrlPatternFilters
- UrlPatternRequestOptions
- WebhookOptions
- ActorInputErrorCode
- ActorOptions
- ApifyConfigurationInput
- ApifyResolvedConfigValues
- ConfigurationOptions
- RequestQueueAccessMode
- StorageIdentifier
- UserFunc
- apifyConfigFields
- log
- createTransformRequestFunction
Other
ActorInputErrorCode
ActorOptions
Options accepted by the Actor constructor. Either pass field-level
overrides (token, inputKey, …) — which the Actor turns into a fresh
Configuration — or pass a pre-built configuration instance. When
both are present, configuration wins and the field-level overrides are
ignored.
ApifyConfigurationInput
ApifyResolvedConfigValues
ConfigurationOptions
Deprecated - Use ApifyConfigurationInput instead.
RequestQueueAccessMode
Determines how an Apify platform request queue is consumed.
'single'— optimized for a single consumer. The client keeps a local estimate of the queue head and never locks requests, which means fewer API calls, better performance and lower cost. Multiple producers may still add requests concurrently, but only one client may consume (fetch and process) them.'shared'— safe for multiple concurrent consumers (e.g. several Actor runs processing one queue). Requests are locked server-side while they are being processed, at the cost of more API calls.
StorageIdentifier
Identifies a storage to open. Can be:
- A plain
stringfor backward compatibility (treated as ID or name) { alias: string }to open a run-scoped storage — see StorageAlias{ id: string }to open by explicit platform ID{ name: string }to open by explicit name
UserFunc
Type parameters
- T = unknown
Type declaration
Returns Awaitable<T>
constapifyConfigFields
Type declaration
actorEventsWsUrl: ConfigField<ZodOptional<ZodString>>
actorId: ConfigField<ZodOptional<ZodString>>
actorPermissionLevel: ConfigField<ZodOptional<ZodString>>
actorPricingInfo: ConfigField<ZodOptional<ZodString>>
actorRunId: ConfigField<ZodOptional<ZodString>>
actorStoragesJson: ConfigField<ZodOptional<ZodString>>
actorTaskId: ConfigField<ZodOptional<ZodString>>
apiBaseUrl: ConfigField<ZodDefault<ZodString>>
apiPublicBaseUrl: ConfigField<ZodDefault<ZodString>>
availableMemoryRatio: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
chargedEventCounts: ConfigField<ZodOptional<ZodString>>
chromeExecutablePath: ConfigField<ZodOptional<ZodString>>
externalcontainerized: ConfigField<ZodOptional<ZodPreprocess<ZodBoolean, unknown>>>
containerPort: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
containerUrl: ConfigField<ZodDefault<ZodString>>
defaultBrowserPath: ConfigField<ZodOptional<ZodString>>
defaultDatasetId: ConfigField<ZodDefault<ZodString>>
defaultKeyValueStoreId: ConfigField<ZodDefault<ZodString>>
defaultRequestQueueId: ConfigField<ZodDefault<ZodString>>
disableBrowserSandbox: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
headless: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
inputKey: ConfigField<ZodDefault<ZodString>>
inputSecretsPrivateKeyFile: ConfigField<ZodOptional<ZodString>>
inputSecretsPrivateKeyPassphrase: ConfigField<ZodOptional<ZodString>>
externalinternalTimeoutMillis: ConfigField<ZodOptional<ZodPreprocess<ZodNumber, unknown>>>
Internal safety-net timeout for a single request, in milliseconds. When unset the crawler derives it from the request handler timeout (twice it, and never below 5 minutes).
isAtHome: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
externallogLevel: ConfigField<ZodOptional<ZodPreprocess<ZodEnum<typeof LogLevel>, unknown>>>
maxTotalChargeUsd: ConfigField<ZodDefault<ZodPipe<ZodPreprocess<ZodNumber, unknown>, ZodTransform<number, number>>>>
externalmaxUsedCpuRatio: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
memoryMbytes: ConfigField<ZodOptional<ZodPreprocess<ZodNumber, unknown>>>
metamorphAfterSleepMillis: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
metaOrigin: ConfigField<ZodOptional<ZodString>>
persistStateIntervalMillis: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
externalpersistStorage: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
proxyHostname: ConfigField<ZodDefault<ZodString>>
proxyPassword: ConfigField<ZodOptional<ZodString>>
proxyPort: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
proxyStatusUrl: ConfigField<ZodDefault<ZodString>>
purgeOnStart: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
standbyPort: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
Deprecated - use
containerPortinsteadstandbyUrl: ConfigField<ZodOptional<ZodString>>
storageClientOptions: ConfigField<ZodOptional<ZodRecord<ZodString, ZodUnknown>>>
externalstorageDir: ConfigField<ZodDefault<ZodString>>
externalsystemInfoIntervalMillis: ConfigField<ZodDefault<ZodPreprocess<ZodNumber, unknown>>>
testPayPerEvent: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
token: ConfigField<ZodOptional<ZodString>>
useChargingLogDataset: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
userId: ConfigField<ZodOptional<ZodString>>
userIsPaying: ConfigField<ZodOptional<ZodString>>
xvfb: ConfigField<ZodDefault<ZodPreprocess<ZodBoolean, unknown>>>
Why Actor.getInput could not produce the input.