1## What are Apify Actors?
2
3- Actors are serverless cloud programs that can perform anything from a simple action, like filling out a web form, to a complex operation, like crawling an entire website or removing duplicates from a large dataset.
4- Actors are programs packaged as Docker images, which accept a well-defined JSON input, perform an action, and optionally produce a well-defined JSON output.
5
6### Apify Actor directory structure
7
8```text
9.actor/
10├── actor.json # Actor config: name, version, env vars, runtime settings
11├── input_schema.json # Input validation & Console form definition
12├── dataset_schema.json # Dataset schema definition
13└── output_schema.json # Specifies where an Actor stores its output
14src/
15└── main.js # Actor entry point and orchestrator
16storage/ # Local storage (mirrors Cloud during development)
17├── datasets/ # Output items (JSON objects)
18├── key_value_stores/ # Files, config, INPUT
19└── request_queues/ # Pending crawl requests
20Dockerfile # Container image definition
21AGENTS.md # AI agent instructions (this file)
22```
23
24## Apify CLI
25
26### Installation
27
28- Install Apify CLI only if it is not already installed.
29- If Apify CLI is not installed, install it using the following commands:
30 - macOS/Linux: `curl -fsSL https://apify.com/install-cli.sh | bash`
31 - Windows: `irm https://apify.com/install-cli.ps1 | iex`
32
33### Apify CLI Commands
34
35```bash
36# Local development
37apify run # Run Actor locally
38
39# Authentication & deployment
40apify login # Authenticate account
41apify push # Deploy to Apify platform
42
43# Help
44apify help # List all commands
45```
46
47## Do
48
49- use the default values for all fields in the actor.json, input_schema.json, output_schema.json, and main.js files
50- use Apify CLI to run the Actor locally, and push it to the Apify platform
51- accept well-defined JSON input and produce structured JSON output
52- use Apify SDK (`apify`) for code running ON Apify platform
53- validate input early with proper error handling and fail gracefully
54- use CheerioCrawler for static HTML content (10x faster than browsers)
55- use PlaywrightCrawler only for JavaScript-heavy sites and dynamic content
56- use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls
57- implement retry strategies with exponential backoff for failed requests
58- use proper concurrency settings (HTTP: 10-50, Browser: 1-5)
59- set sensible defaults in `.actor/input_schema.json` for all optional fields
60- set up output schema in `.actor/output_schema.json`
61- clean and validate data before pushing to dataset
62- use semantic CSS selectors and fallback strategies for missing elements
63- respect robots.txt, ToS, and implement rate limiting with delays
64- check which tools (cheerio/playwright/crawlee) are installed before applying guidance
65
66## Don't
67
68- do not run apify create command
69- do not rely on `Dataset.getInfo()` for final counts on Cloud platform
70- do not use browser crawlers when HTTP/Cheerio works (massive performance gains with HTTP)
71- do not hard code values that should be in input schema or environment variables
72- do not skip input validation or error handling
73- do not overload servers - use appropriate concurrency and delays
74- do not scrape prohibited content or ignore Terms of Service
75- do not store personal/sensitive data unless explicitly permitted
76- do not use deprecated options like `requestHandlerTimeoutMillis` on CheerioCrawler (v3.x)
77- do not use `additionalHttpHeaders` - use `preNavigationHooks` instead
78
79## Actor Input Schema
80
81The input schema defines the input parameters for an Actor. It's a JSON object comprising various field types supported by the Apify platform.
82
83### Structure
84
85```json
86{
87 "title": "<INPUT-SCHEMA-TITLE>",
88 "type": "object",
89 "schemaVersion": 1,
90 "properties": {
91 /* define input fields here */
92 },
93 "required": []
94}
95```
96
97## Actor Output Schema
98
99The Actor output schema builds upon the schemas for the dataset and key-value store. It specifies where an Actor stores its output and defines templates for accessing that output. Apify Console uses these output definitions to display run results.
100
101### Structure
102
103```json
104{
105 "actorOutputSchemaVersion": 1,
106 "title": "<OUTPUT-SCHEMA-TITLE>",
107 "properties": {
108 /* define your outputs here */
109 }
110}
111```
112
113### Output Schema Template Variables
114
115- `links` (object) - Contains quick links to most commonly used URLs
116- `links.publicRunUrl` (string) - Public run url in format `https://console.apify.com/view/runs/:runId`
117- `links.consoleRunUrl` (string) - Console run url in format `https://console.apify.com/actors/runs/:runId`
118- `links.apiRunUrl` (string) - API run url in format `https://api.apify.com/v2/actor-runs/:runId`
119- `links.apiDefaultDatasetUrl` (string) - API url of default dataset in format `https://api.apify.com/v2/datasets/:defaultDatasetId`
120- `links.apiDefaultKeyValueStoreUrl` (string) - API url of default key-value store in format `https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId`
121- `links.containerRunUrl` (string) - URL of a webserver running inside the run in format `https://<containerId>.runs.apify.net/`
122- `run` (object) - Contains information about the run same as it is returned from the `GET Run` API endpoint
123- `run.defaultDatasetId` (string) - ID of the default dataset
124- `run.defaultKeyValueStoreId` (string) - ID of the default key-value store
125
126## Dataset Schema Specification
127
128The dataset schema defines how your Actor's output data is structured, transformed, and displayed in the Output tab in the Apify Console.
129
130### Structure
131
132```json
133{
134 "actorSpecification": 1,
135 "fields": {},
136 "views": {
137 "<VIEW_NAME>": {
138 "title": "string (required)",
139 "description": "string (optional)",
140 "transformation": {
141 "fields": ["string (required)"],
142 "unwind": ["string (optional)"],
143 "flatten": ["string (optional)"],
144 "omit": ["string (optional)"],
145 "limit": "integer (optional)",
146 "desc": "boolean (optional)"
147 },
148 "display": {
149 "component": "table (required)",
150 "properties": {
151 "<FIELD_NAME>": {
152 "label": "string (optional)",
153 "format": "text|number|date|link|boolean|image|array|object (optional)"
154 }
155 }
156 }
157 }
158 }
159}
160```
161
162**Dataset Schema Properties:**
163
164- `actorSpecification` (integer, required) - Specifies the version of dataset schema structure document (currently only version 1)
165- `fields` (JSONSchema object, required) - Schema of one dataset object (use JsonSchema Draft 2020-12 or compatible)
166- `views` (DatasetView object, required) - Object with API and UI views description
167
168**DatasetView Properties:**
169
170- `title` (string, required) - Visible in UI Output tab and API
171- `description` (string, optional) - Only available in API response
172- `transformation` (ViewTransformation object, required) - Data transformation applied when loading from Dataset API
173- `display` (ViewDisplay object, required) - Output tab UI visualization definition
174
175**ViewTransformation Properties:**
176
177- `fields` (string[], required) - Fields to present in output (order matches column order)
178- `unwind` (string[], optional) - Deconstructs nested children into parent object
179- `flatten` (string[], optional) - Transforms nested object into flat structure
180- `omit` (string[], optional) - Removes specified fields from output
181- `limit` (integer, optional) - Maximum number of results (default: all)
182- `desc` (boolean, optional) - Sort order (true = newest first)
183
184**ViewDisplay Properties:**
185
186- `component` (string, required) - Only `table` is available
187- `properties` (Object, optional) - Keys matching `transformation.fields` with ViewDisplayProperty values
188
189**ViewDisplayProperty Properties:**
190
191- `label` (string, optional) - Table column header
192- `format` (string, optional) - One of: `text`, `number`, `date`, `link`, `boolean`, `image`, `array`, `object`
193
194## Key-Value Store Schema Specification
195
196The key-value store schema organizes keys into logical groups called collections for easier data management.
197
198### Structure
199
200```json
201{
202 "actorKeyValueStoreSchemaVersion": 1,
203 "title": "string (required)",
204 "description": "string (optional)",
205 "collections": {
206 "<COLLECTION_NAME>": {
207 "title": "string (required)",
208 "description": "string (optional)",
209 "key": "string (conditional - use key OR keyPrefix)",
210 "keyPrefix": "string (conditional - use key OR keyPrefix)",
211 "contentTypes": ["string (optional)"],
212 "jsonSchema": "object (optional)"
213 }
214 }
215}
216```
217
218**Key-Value Store Schema Properties:**
219
220- `actorKeyValueStoreSchemaVersion` (integer, required) - Version of key-value store schema structure document (currently only version 1)
221- `title` (string, required) - Title of the schema
222- `description` (string, optional) - Description of the schema
223- `collections` (Object, required) - Object where each key is a collection ID and value is a Collection object
224
225**Collection Properties:**
226
227- `title` (string, required) - Collection title shown in UI tabs
228- `description` (string, optional) - Description appearing in UI tooltips
229- `key` (string, conditional) - Single specific key for this collection
230- `keyPrefix` (string, conditional) - Prefix for keys included in this collection
231- `contentTypes` (string[], optional) - Allowed content types for validation
232- `jsonSchema` (object, optional) - JSON Schema Draft 07 format for `application/json` content type validation
233
234Either `key` or `keyPrefix` must be specified for each collection, but not both.
235
236## Apify MCP Tools
237
238If MCP server is configured, use these tools for documentation:
239
240- `search-apify-docs` - Search documentation
241- `fetch-apify-docs` - Get full doc pages
242
243Otherwise, reference: `@https://mcp.apify.com/`
244
245## Resources
246
247- [docs.apify.com/llms.txt](https://docs.apify.com/llms.txt) - Quick reference
248- [docs.apify.com/llms-full.txt](https://docs.apify.com/llms-full.txt) - Complete docs
249- [crawlee.dev](https://crawlee.dev) - Crawlee documentation
250- [whitepaper.actor](https://raw.githubusercontent.com/apify/actor-whitepaper/refs/heads/master/README.md) - Complete Actor specification