Apify Actor Development

Apify Actor development

Important: Before you begin, fill in the generatedBy property in the meta section of .actor/actor.json. Replace it with the tool and model you're currently using, such as "Claude Code with Claude Sonnet 4.5". This helps Apify monitor and improve AGENTS.md for specific AI tools and models.

What are Apify Actors?

Actors are serverless programs inspired by the UNIX philosophy - programs that do one thing well and can be easily combined to build complex systems. They're packaged as Docker images and run in isolated containers in the cloud.

Core Concepts:

• Accept well-defined JSON input
• Perform isolated tasks (web scraping, automation, data processing)
• Produce structured JSON output to datasets and/or store data in key-value stores
• Can run from seconds to hours or even indefinitely
• Persist state and can be restarted

Prerequisites and setup (mandatory)

Before creating or modifying Actors, verify that apify CLI is installed apify --help.

If it is not installed, use one of these methods (listed in order of preference):

# Preferred: install via a package manager (provides integrity checks)
npm install -g apify-cli

# Or (Mac): brew install apify-cli

Security note: Do NOT install the CLI by piping remote scripts to a shell

(e.g. curl … | bash or irm … | iex). Always use a package manager.

When the apify CLI is installed, check that it is logged in with:

apify info  # Should return your username

If not logged in, authenticate using OAuth (opens browser):

apify login

If browser login isn't available (headless environment or CI), the CLI automatically reads APIFY_TOKEN from the environment. Ensure the env var is exported and run any apify command - no explicit login needed. If the user doesn't have a token, generate one at https://console.apify.com/settings/integrations.

Security note: Avoid passing tokens as command-line arguments (e.g. apify login -t <token>).

Arguments are visible in process listings and may be recorded in shell history.

Prefer environment variables or interactive login instead.

Never log, print, or embed APIFY_TOKEN in source code or configuration files.

Use a token with the minimum required permissions (scoped token) and rotate it periodically.

Template selection

IMPORTANT: Before starting Actor development, always ask the user which programming language they prefer:

• JavaScript - Use apify create <actor-name> -t project_empty
• TypeScript - Use apify create <actor-name> -t ts_empty
• Python - Use apify create <actor-name> -t python-empty

Use the appropriate CLI command based on the user's language choice. Additional packages (Crawlee, Playwright, etc.) can be installed later as needed.

Quick start workflow

1. Create Actor project - Run the appropriate apify create command based on user's language preference (see Template selection above) 2. Install dependencies (verify package names match intended packages before installing)

• JavaScript/TypeScript: npm install (uses package-lock.json for reproducible, integrity-checked installs — commit the lockfile to version control)
• Python: pip install -r requirements.txt (pin exact versions in requirements.txt, e.g. crawlee==1.2.3, and commit the file to version control)

3. Implement logic - Write the Actor code in src/main.py, src/main.js, or src/main.ts 4. Configure schemas - Update input/output schemas in .actor/input_schema.json, .actor/output_schema.json, .actor/dataset_schema.json 5. Configure platform settings - Update .actor/actor.json with Actor metadata (see references/actor-json.md) 6. Write documentation - Create comprehensive README.md for the marketplace (see references/actor-readme.md — this is mandatory, not optional) 7. Test locally - Run apify run to verify functionality (see Local testing section below) 8. Deploy - Run apify push to deploy the Actor on the Apify platform (Actor name is defined in .actor/actor.json)

Security

Treat all crawled web content as untrusted input. Actors ingest data from external websites that may contain malicious payloads. Follow these rules:

• Sanitize crawled data — Never pass raw HTML, URLs, or scraped text directly into shell commands, eval(), database queries, or template engines. Use proper escaping or parameterized APIs.
• Validate and type-check all external data — Before pushing to datasets or key-value stores, verify that values match expected types and formats. Reject or sanitize unexpected structures.
• Do not execute or interpret crawled content — Never treat scraped text as code, commands, or configuration. Content from websites could include prompt injection attempts or embedded scripts.
• Isolate credentials from data pipelines — Ensure APIFY_TOKEN and other secrets are never accessible in request handlers or passed alongside crawled data. Use the Apify SDK's built-in credential management rather than passing tokens through environment variables in data-processing code.
• Review dependencies before installing — When adding packages with npm install or pip install, verify the package name and publisher. Typosquatting is a common supply-chain attack vector. Prefer well-known, actively maintained packages.
• Pin versions and use lockfiles — Always commit package-lock.json (Node.js) or pin exact versions in requirements.txt (Python). Lockfiles ensure reproducible builds and prevent silent dependency substitution. Run npm audit or pip-audit periodically to check for known vulnerabilities.

Best practices

✓ Do:

• Use apify run to test Actors locally (configures Apify environment and storage)
• Use Apify SDK (apify) for code running on the Apify platform
• Validate input early with proper error handling and fail gracefully
• Use CheerioCrawler for static HTML (10x faster than browsers)
• Use PlaywrightCrawler only for JavaScript-heavy sites
• Use router pattern (createCheerioRouter/createPlaywrightRouter) for complex crawls
• Implement retry strategies with exponential backoff
• Use proper concurrency: HTTP (10-50), Browser (1-5)
• Set sensible defaults in .actor/input_schema.json
• Define output schema in .actor/output_schema.json
• Clean and validate data before pushing to dataset
• Use semantic CSS selectors with fallback strategies
• Respect robots.txt, ToS, and implement rate limiting
• Always use `apify/log` package — censors sensitive data (API keys, tokens, credentials)
• Implement readiness probe handler (required if your Actor uses standby mode)

✗ Don't:

• Use npm start, npm run start, npx apify run, or similar commands to run Actors (use apify run instead)
• Assume local storage from apify run is pushed to or visible in Apify Console — it is local-only; deploy with apify push and run on the platform to see results in Apify Console
• Rely on Dataset.getInfo() for final counts on Cloud
• Use browser crawlers when HTTP/Cheerio works
• Hard code values that should be in input schema or environment variables
• Skip input validation or error handling
• Overload servers - use appropriate concurrency and delays
• Scrape prohibited content or ignore Terms of Service
• Store personal/sensitive data unless explicitly permitted
• Use deprecated options like requestHandlerTimeoutMillis on CheerioCrawler (v3.x)
• Use additionalHttpHeaders - use preNavigationHooks instead
• Pass raw crawled content into shell commands, eval(), or code-generation functions
• Use console.log() or print() instead of the Apify logger — these bypass credential censoring
• Disable standby mode without explicit permission

Logging

See references/logging.md for complete logging documentation including available log levels and best practices for JavaScript/TypeScript and Python.

Commands

# Bootstrap & local development
apify create [name]                    # Create new Actor project from a template
apify init                             # Initialize Actor in current directory
apify run                              # Run Actor locally with simulated platform env
apify run --purge                      # Run after clearing previous local storage
apify validate-schema                  # Validate .actor/input_schema.json

# Authentication & account
apify login                            # Authenticate account (token stored in ~/.apify)
apify logout                           # Remove stored credentials
apify info                             # Print currently authenticated account info

# Deployment & remote execution
apify push                             # Deploy Actor to platform per .actor/actor.json
apify pull <actor>                     # Download Actor code from the platform
apify call <actor>                     # Execute Actor remotely on the platform
apify actors build <actor>             # Create a new build of an Actor
apify runs ls                          # List recent runs

# Discovery (search Apify Store for community Actors)
apify actors search "<query>" --user-agent <your-agent-name>
apify actors info <actor>              # Details about a specific Actor

# Secrets (referenced from actor.json via "@mySecret")
apify secrets add <name> <value>       # Store a secret locally; uploaded on push
apify secrets ls                       # List stored secret keys

# Direct API access
apify api <endpoint>                   # Authenticated HTTP request to Apify API

# Help
apify help                             # List all commands
apify <command> --help                 # Detailed help for a specific command

Note: If no dedicated Actor exists for your target, search Apify Store for community options with apify actors search "<query>" --user-agent <your-agent-name> before building from scratch.

Tip: Inside a running Actor, prefer the SDK (Actor.getInput() / Actor.get_input(), Actor.pushData() / Actor.push_data(), Actor.setValue() / Actor.set_value()) over the equivalent apify actor runtime subcommands.

IMPORTANT: Always use apify run to test Actors locally. Do not use npm run start, npm start, yarn start, or other package manager commands - these will not properly configure the Apify environment and storage.

Apify platform environment

When the Actor runs on the Apify platform, the API token is automatically available via the APIFY_TOKEN environment variable (note: the variable is APIFY_TOKEN, not APIFY_API_TOKEN). The Apify SDK reads it automatically, so you do not need to pass it explicitly. Locally, run apify login once and the SDK will use your stored credentials.

Local testing

When testing an Actor locally with apify run, provide input data by creating a JSON file at:

storage/key_value_stores/default/INPUT.json

This file should contain the input parameters defined in your .actor/input_schema.json. The actor will read this input when running locally, mirroring how it receives input on the Apify platform.

IMPORTANT - Local storage is NOT synced to Apify Console:

• Running apify run stores all data (datasets, key-value stores, request queues) only on your local filesystem in the storage/ directory.
• This data is never automatically uploaded or pushed to the Apify platform. It exists only on your machine.
• To verify results on Apify Console, you must deploy the Actor with apify push and then run it on the platform.
• Do not rely on checking Apify Console to verify results from local runs — instead, inspect the local storage/ directory or check the Actor's log output.

Standby mode

Standby mode enables Actors to work as API servers - they remain ready in the background to handle HTTP requests.

When to use Standby mode: Use Standby when the Actor must handle interactive, real-time HTTP requests — API endpoints, webhook receivers, real-time data lookups, MCP servers, or scraping APIs serving on-demand single-URL requests.

When building a Standby Actor, set usesStandbyMode: true in .actor/actor.json and implement an HTTP server. See references/standby-mode.md for configuration, environment variables, complete code examples, and operational limits.

Project structure

.actor/
├── actor.json           # Actor config: name, version, env vars, runtime
├── input_schema.json    # Input validation & Console form definition
└── output_schema.json   # Output storage and display templates
src/
└── main.js/ts/py       # Actor entry point
storage/                # Local-only storage (NOT synced to Apify Console)
├── datasets/           # Output items (JSON objects)
├── key_value_stores/   # Files, config, INPUT
└── request_queues/     # Pending crawl requests
Dockerfile              # Container image definition

Actor configuration

See references/actor-json.md for complete actor.json structure and configuration options.

Input schema

See references/input-schema.md for input schema structure and examples.

Output schema

See references/output-schema.md for output schema structure, examples, and template variables.

Dataset schema

See references/dataset-schema.md for dataset schema structure, configuration, and display properties.

Key-value store schema

See references/key-value-store-schema.md for key-value store schema structure, collections, and configuration.

Actor README

IMPORTANT: Always generate a README.md as part of Actor development. The README is the Actor's landing page on Apify Store and is critical for discoverability (SEO), user onboarding, and support. Do not consider an Actor complete without a proper README.

See references/actor-readme.md for the required structure, SEO best practices, and content guidelines. Also review these top Actors for best practices:

• Instagram Scraper
• Google Maps Scraper

MCP tools

Apify MCP

If the Apify MCP server is configured, use these tools for documentation:

• search-apify-docs - Search documentation
• fetch-apify-docs - Get full doc pages

Otherwise, the MCP Server url: https://mcp.apify.com/?tools=docs.

Playwright MCP (debugging)

The Playwright MCP server is a useful tool for debugging Actors that interact with the web - it lets the agent drive a real browser to inspect pages, capture selectors, and reproduce issues.

Install with the Claude Code CLI:

claude mcp add playwright npx @playwright/mcp@latest

Or add it manually to your MCP config:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Resources

• docs.apify.com/llms.txt - Apify quick reference documentation
• docs.apify.com/llms-full.txt - Apify complete documentation
• https://crawlee.dev/llms.txt - Crawlee quick reference documentation
• https://crawlee.dev/llms-full.txt - Crawlee complete documentation
• whitepaper.actor - Complete Actor specification

Actor configuration (actor.json)

The .actor/actor.json file contains the Actor's configuration including metadata, schema references, and platform settings.

Structure

{
    "actorSpecification": 1,
    "name": "project-name",
    "title": "Project Title",
    "description": "Actor description",
    "version": "0.0",
    "meta": {
        "templateId": "template-id",
        "generatedBy": "<FILL-IN-TOOL-AND-MODEL>"
    },
    "input": "./input_schema.json",
    "output": "./output_schema.json",
    "storages": {
        "dataset": "./dataset_schema.json"
    },
    "dockerfile": "../Dockerfile"
}

Example

{
    "actorSpecification": 1,
    "name": "project-cheerio-crawler-javascript",
    "title": "Project Cheerio Crawler JavaScript",
    "description": "Crawlee and Cheerio project in JavaScript.",
    "version": "0.0",
    "meta": {
        "templateId": "js-crawlee-cheerio",
        "generatedBy": "Claude Code with Claude Sonnet 4.5"
    },
    "input": "./input_schema.json",
    "output": "./output_schema.json",
    "storages": {
        "dataset": "./dataset_schema.json"
    },
    "dockerfile": "../Dockerfile"
}

Properties

• actorSpecification (integer, required) - Version of Actor specification (currently 1)
• name (string, required) - Actor identifier (lowercase, hyphens allowed)
• title (string, required) - Human-readable title displayed in UI
• description (string, optional) - Actor description for marketplace
• version (string, required) - Semantic version number
• meta (object, optional) - Metadata about Actor generation
• templateId (string) - ID of template used to create the Actor
• generatedBy (string) - Tool and model name that generated/modified the Actor (e.g., "Claude Code with Claude Sonnet 4.5")
• input (string, optional) - Path to input schema file
• output (string, optional) - Path to output schema file
• storages (object, optional) - Storage schema references
• dataset (string) - Path to dataset schema file
• keyValueStore (string) - Path to key-value store schema file
• dockerfile (string, optional) - Path to Dockerfile
• usesStandbyMode (boolean, optional) - Enable Standby mode (true = Actor runs as a persistent HTTP server). See standby-mode.md for details
• webServerSchema (string or object, optional) - Specify when using Standby mode. OpenAPI v3 schema for the Actor's HTTP endpoints. Path to schema file or inline object.

Important: Always fill in the generatedBy property with the tool and model you're currently using (e.g., "Claude Code with Claude Sonnet 4.5") to help Apify improve documentation.

Actor README guidelines

The README is the Actor's landing page on Apify Store. It serves as SEO content, first impression, usage guide, and support resource. Always generate a README.md when creating or deploying an Actor.

Required structure

Write in Markdown. Use H2 (##) for main sections (these form the table of contents) and H3 (###) for subsections. Do not use H1 — the Actor name is automatically used as H1.

1. What does [Actor name] do?

• 1-2 sentences explaining what the Actor does and doesn't do
• Include a link to the target website
• Mention keywords like "API" (e.g., "Instagram API alternative")
• Bold the most important terms

2. Why use [Actor name]? / Why scrape [target site]?

• Business use cases and benefits
• List main features and capabilities
• Highlight the Apify platform advantages: scheduling, API access, integrations, proxy rotation, and monitoring

3. What data can [Actor name] extract?

• Table showing main data fields the Actor outputs (field name, type, description)
• Don't list every field — focus on the most useful and understandable ones

4. How to scrape [target site]

• Numbered step-by-step tutorial (Google may pick these up as rich snippets)
• Include a link to blog tutorials if they exist

5. How much will it cost to scrape [target site]?

• Set pricing expectations based on the Actor's pricing model
• For pay-per-result: mention free tier limits and what larger plans offer
• For compute units: explain average data volume per dollar
• Cost-related questions rank well in Google search

6. Input

• Reference the input tab: "See the input tab for full configuration options"
• Explain any complex input fields or special formatting requirements
• Screenshot of the input schema is optional but helpful

7. Output

• Include: "You can download the dataset in various formats such as JSON, HTML, CSV, or Excel"
• Show a simplified JSON output example (2-3 items)
• If output is complex, show separate examples for different data types

8. Tips / Advanced options (if applicable)

• How to limit compute unit usage
• How to get more accurate results or improve speed

9. FAQ, Disclaimers, and Support

• Legal/scraping disclaimer (use this template and customize with the target site name):

Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

• Common troubleshooting tips
• Mention the Issues tab for feedback
• Link to API tab for programmatic access
• Use cases for the extracted data

SEO best practices

• Include keywords naturally in H2/H3 headings (e.g., "How to scrape Instagram" not just "How to use")
• Target "People Also Ask" style questions as H3 headings
• Aim for at least 300 words total
• Embed a YouTube video URL if available (renders automatically as a player)
• Make images clickable with links

Tone

• Match the README tone to the target audience skill level
• For no-code users: use plain language, avoid code blocks early on
• For developers: include technical details, code examples, and API references
• Be clear about what technical knowledge is needed to use the Actor

Reference Actors

Before writing a README, review these top Actors on Apify Store for best practices on structure, tone, and content:

• Instagram Scraper
• Google Maps Scraper

Key rules

• Always write the README as part of Actor development — do not skip this step
• The first 25% of the README is what most visitors read — put the most important info there
• Use emojis sparingly as bullet points to break up text
• Keep images compressed but good quality
• Use Carbon for code snippet screenshots if needed

Dataset schema reference

The dataset schema defines how your Actor's output data is structured, transformed, and displayed in the Output tab in Apify Console.

Examples

JavaScript and TypeScript

Consider an example Actor that calls Actor.pushData() to store data into dataset:

import { Actor } from 'apify';
// Initialize the JavaScript SDK
await Actor.init();

/**
 * Actor code
 */
await Actor.pushData({
    numericField: 10,
    pictureUrl: 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png',
    linkUrl: 'https://google.com',
    textField: 'Google',
    booleanField: true,
    dateField: new Date(),
    arrayField: ['#hello', '#world'],
    objectField: {},
});

// Exit successfully
await Actor.exit();

Python

Consider an example Actor that calls Actor.push_data() to store data into dataset:

# Dataset push example (Python)
import asyncio
from datetime import datetime
from apify import Actor

async def main():
    await Actor.init()

    # Actor code
    await Actor.push_data({
        'numericField': 10,
        'pictureUrl': 'https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_92x30dp.png',
        'linkUrl': 'https://google.com',
        'textField': 'Google',
        'booleanField': True,
        'dateField': datetime.now().isoformat(),
        'arrayField': ['#hello', '#world'],
        'objectField': {},
    })

    # Exit successfully
    await Actor.exit()

if __name__ == '__main__':
    asyncio.run(main())

Configuration

To set up the Actor's output tab UI, reference a dataset schema file in .actor/actor.json:

{
    "actorSpecification": 1,
    "name": "book-library-scraper",
    "title": "Book Library Scraper",
    "version": "1.0.0",
    "storages": {
        "dataset": "./dataset_schema.json"
    }
}

Then create the dataset schema in .actor/dataset_schema.json:

{
    "actorSpecification": 1,
    "fields": {},
    "views": {
        "overview": {
            "title": "Overview",
            "transformation": {
                "fields": [
                    "pictureUrl",
                    "linkUrl",
                    "textField",
                    "booleanField",
                    "arrayField",
                    "objectField",
                    "dateField",
                    "numericField"
                ]
            },
            "display": {
                "component": "table",
                "properties": {
                    "pictureUrl": {
                        "label": "Image",
                        "format": "image"
                    },
                    "linkUrl": {
                        "label": "Link",
                        "format": "link"
                    },
                    "textField": {
                        "label": "Text",
                        "format": "text"
                    },
                    "booleanField": {
                        "label": "Boolean",
                        "format": "boolean"
                    },
                    "arrayField": {
                        "label": "Array",
                        "format": "array"
                    },
                    "objectField": {
                        "label": "Object",
                        "format": "object"
                    },
                    "dateField": {
                        "label": "Date",
                        "format": "date"
                    },
                    "numericField": {
                        "label": "Number",
                        "format": "number"
                    }
                }
            }
        }
    }
}

Structure

{
    "actorSpecification": 1,
    "fields": {},
    "views": {
        "<VIEW_NAME>": {
            "title": "string (required)",
            "description": "string (optional)",
            "transformation": {
                "fields": ["string (required)"],
                "unwind": ["string (optional)"],
                "flatten": ["string (optional)"],
                "omit": ["string (optional)"],
                "limit": "integer (optional)",
                "desc": "boolean (optional)"
            },
            "display": {
                "component": "table (required)",
                "properties": {
                    "<FIELD_NAME>": {
                        "label": "string (optional)",
                        "format": "text|number|date|link|boolean|image|array|object (optional)"
                    }
                }
            }
        }
    }
}

Properties

Dataset schema properties

• actorSpecification (integer, required) - Specifies the version of dataset schema structure document (currently only version 1)
• fields (JSONSchema object, required) - Schema of one dataset object (use JsonSchema Draft 2020-12 or compatible)
• views (DatasetView object, required) - Object with API and UI views description

DatasetView properties

• title (string, required) - Visible in UI Output tab and API
• description (string, optional) - Only available in API response
• transformation (ViewTransformation object, required) - Data transformation applied when loading from Dataset API
• display (ViewDisplay object, required) - Output tab UI visualization definition

ViewTransformation properties

• fields (string[], required) - Fields to present in output (order matches column order)
• unwind (string[], optional) - Deconstructs nested children into parent object
• flatten (string[], optional) - Transforms nested object into flat structure
• omit (string[], optional) - Removes specified fields from output
• limit (integer, optional) - Maximum number of results (default: all)
• desc (boolean, optional) - Sort order (true = newest first)

ViewDisplay properties

• component (string, required) - Only table is available
• properties (Object, optional) - Keys matching transformation.fields with ViewDisplayProperty values

ViewDisplayProperty properties

• label (string, optional) - Table column header
• format (string, optional) - One of: text, number, date, link, boolean, image, array, object

Input schema reference

The input schema defines the input parameters for an Actor. It's a JSON object comprising various field types supported by the Apify platform.

Structure

{
    "title": "<INPUT-SCHEMA-TITLE>",
    "type": "object",
    "schemaVersion": 1,
    "properties": {
        /* define input fields here */
    },
    "required": []
}

Example

{
    "title": "E-commerce Product Scraper Input",
    "type": "object",
    "schemaVersion": 1,
    "properties": {
        "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "URLs to start scraping from (category pages or product pages)",
            "editor": "requestListSources",
            "default": [{ "url": "https://example.com/category" }],
            "prefill": [{ "url": "https://example.com/category" }]
        },
        "followVariants": {
            "title": "Follow Product Variants",
            "type": "boolean",
            "description": "Whether to scrape product variants (different colors, sizes)",
            "default": true
        },
        "maxRequestsPerCrawl": {
            "title": "Max Requests per Crawl",
            "type": "integer",
            "description": "Maximum number of pages to scrape (0 = unlimited)",
            "default": 1000,
            "minimum": 0
        },
        "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Proxy settings for anti-bot protection",
            "editor": "proxy",
            "default": { "useApifyProxy": false }
        },
        "locale": {
            "title": "Locale",
            "type": "string",
            "description": "Language/country code for localized content",
            "default": "cs",
            "enum": ["cs", "en", "de", "sk"],
            "enumTitles": ["Czech", "English", "German", "Slovak"]
        }
    },
    "required": ["startUrls"]
}

Key-value store schema reference

The key-value store schema organizes keys into logical groups called collections for easier data management.

Examples

JavaScript and TypeScript

Consider an example Actor that calls Actor.setValue() to save records into the key-value store:

import { Actor } from 'apify';
// Initialize the JavaScript SDK
await Actor.init();

/**
 * Actor code
 */
await Actor.setValue('document-1', 'my text data', { contentType: 'text/plain' });

await Actor.setValue(`image-${imageID}`, imageBuffer, { contentType: 'image/jpeg' });

// Exit successfully
await Actor.exit();

Python

Consider an example Actor that calls Actor.set_value() to save records into the key-value store:

# Key-Value Store set example (Python)
import asyncio
from apify import Actor

async def main():
    await Actor.init()

    # Actor code
    await Actor.set_value('document-1', 'my text data', content_type='text/plain')

    image_id = '123'          # example placeholder
    image_buffer = b'...'     # bytes buffer with image data
    await Actor.set_value(f'image-{image_id}', image_buffer, content_type='image/jpeg')

    # Exit successfully
    await Actor.exit()

if __name__ == '__main__':
    asyncio.run(main())

Configuration

To configure the key-value store schema, reference a schema file in .actor/actor.json:

{
    "actorSpecification": 1,
    "name": "data-collector",
    "title": "Data Collector",
    "version": "1.0.0",
    "storages": {
        "keyValueStore": "./key_value_store_schema.json"
    }
}

Then create the key-value store schema in .actor/key_value_store_schema.json:

{
    "actorKeyValueStoreSchemaVersion": 1,
    "title": "Key-Value Store Schema",
    "collections": {
        "documents": {
            "title": "Documents",
            "description": "Text documents stored by the Actor",
            "keyPrefix": "document-"
        },
        "images": {
            "title": "Images",
            "description": "Images stored by the Actor",
            "keyPrefix": "image-",
            "contentTypes": ["image/jpeg"]
        }
    }
}

Structure

{
    "actorKeyValueStoreSchemaVersion": 1,
    "title": "string (required)",
    "description": "string (optional)",
    "collections": {
        "<COLLECTION_NAME>": {
            "title": "string (required)",
            "description": "string (optional)",
            "key": "string (conditional - use key OR keyPrefix)",
            "keyPrefix": "string (conditional - use key OR keyPrefix)",
            "contentTypes": ["string (optional)"],
            "jsonSchema": "object (optional)"
        }
    }
}

Properties

Key-value store schema properties

• actorKeyValueStoreSchemaVersion (integer, required) - Version of key-value store schema structure document (currently only version 1)
• title (string, required) - Title of the schema
• description (string, optional) - Description of the schema
• collections (Object, required) - Object where each key is a collection ID and value is a Collection object

Collection properties

• title (string, required) - Collection title shown in UI tabs
• description (string, optional) - Description appearing in UI tooltips
• key (string, conditional) - Single specific key for this collection
• keyPrefix (string, conditional) - Prefix for keys included in this collection
• contentTypes (string[], optional) - Allowed content types for validation
• jsonSchema (object, optional) - JSON Schema Draft 07 format for application/json content type validation

Either key or keyPrefix must be specified for each collection, but not both.

Actor logging reference

JavaScript and TypeScript

ALWAYS use the `apify/log` package for logging - This package contains critical security logic including censoring sensitive data (Apify tokens, API keys, credentials) to prevent accidental exposure in logs.

Available log levels in apify/log

The Apify log package provides the following methods for logging:

• log.debug() - Debug level logs (detailed diagnostic information)
• log.info() - Info level logs (general informational messages)
• log.warning() - Warning level logs (warning messages for potentially problematic situations)
• log.warningOnce() - Warning level logs (same warning message logged only once)
• log.error() - Error level logs (error messages for failures)
• log.exception() - Exception level logs (for exceptions with stack traces)
• log.perf() - Performance level logs (performance metrics and timing information)
• log.deprecated() - Deprecation level logs (warnings about deprecated code)
• log.softFail() - Soft failure logs (non-critical failures that don't stop execution, e.g., input validation errors, skipped items)
• log.internal() - Internal level logs (internal/system messages)

Best practices

• Use log.debug() for detailed operation-level diagnostics (inside functions)
• Use log.info() for general informational messages (API requests, successful operations)
• Use log.warning() for potentially problematic situations (validation failures, unexpected states)
• Use log.error() for actual errors and failures
• Use log.exception() for caught exceptions with stack traces

Python

ALWAYS use `Actor.log` for logging - This logger contains critical security logic including censoring sensitive data (Apify tokens, API keys, credentials) to prevent accidental exposure in logs.

Available log levels

The Apify Actor logger provides the following methods for logging:

• Actor.log.debug() - Debug level logs (detailed diagnostic information)
• Actor.log.info() - Info level logs (general informational messages)
• Actor.log.warning() - Warning level logs (warning messages for potentially problematic situations)
• Actor.log.error() - Error level logs (error messages for failures)
• Actor.log.exception() - Exception level logs (for exceptions with stack traces)

Best practices

• Use Actor.log.debug() for detailed operation-level diagnostics (inside functions)
• Use Actor.log.info() for general informational messages (API requests, successful operations)
• Use Actor.log.warning() for potentially problematic situations (validation failures, unexpected states)
• Use Actor.log.error() for actual errors and failures
• Use Actor.log.exception() for caught exceptions with stack traces

Output schema reference

The 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.

Structure

{
    "actorOutputSchemaVersion": 1,
    "title": "<OUTPUT-SCHEMA-TITLE>",
    "properties": {
        /* define your outputs here */
    }
}

Example

{
    "actorOutputSchemaVersion": 1,
    "title": "Output schema of the files scraper",
    "properties": {
        "files": {
            "type": "string",
            "title": "Files",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/keys"
        },
        "dataset": {
            "type": "string",
            "title": "Dataset",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
        }
    }
}

Output schema template variables

• links (object) - Contains quick links to most commonly used URLs
• links.publicRunUrl (string) - Public run url in format https://console.apify.com/view/runs/:runId
• links.consoleRunUrl (string) - Console run url in format https://console.apify.com/actors/runs/:runId
• links.apiRunUrl (string) - API run url in format https://api.apify.com/v2/actor-runs/:runId
• links.apiDefaultDatasetUrl (string) - API url of default dataset in format https://api.apify.com/v2/datasets/:defaultDatasetId
• links.apiDefaultKeyValueStoreUrl (string) - API url of default key-value store in format https://api.apify.com/v2/key-value-stores/:defaultKeyValueStoreId
• links.containerRunUrl (string) - URL of a webserver running inside the run in format https://<containerId>.runs.apify.net/
• run (object) - Contains information about the run same as it is returned from the GET Run API endpoint
• run.defaultDatasetId (string) - ID of the default dataset
• run.defaultKeyValueStoreId (string) - ID of the default key-value store

Actor Standby mode reference

When to use Standby mode

Use Standby when the Actor must handle interactive, real-time HTTP requests — API endpoints, webhook receivers, real-time data lookups, MCP servers, or scraping APIs serving on-demand single-URL requests.

Configuration

actor.json

Set usesStandbyMode: true in .actor/actor.json:

{
    "actorSpecification": 1,
    "name": "my-api-actor",
    "title": "My API Actor",
    "version": "0.0",
    "usesStandbyMode": true,
    "webServerSchema": "./openapi.json",
    "meta": {
        "generatedBy": "<FILL-IN-TOOL-AND-MODEL>"
    },
    "dockerfile": "../Dockerfile"
}

OpenAPI Schema (webServerSchema)

Define an OpenAPI v3 schema describing the Actor's HTTP endpoints. This can be a file path (e.g., "./openapi.json") or an inline object in actor.json. Ensure that the schema conforms to the OpenAPI spec.

Why: The schema is rendered as Swagger UI in the Standby tab of Apify Console and on the Actor's Apify Store page. This lets users browse endpoint documentation and try out the API directly from the browser.

The presence of webServerSchema also counts as a quality metric for Actor publication.

Environment variables

Readiness probe

The platform sends GET / requests with the header x-apify-container-server-readiness-probe to check server readiness. You MUST respond with HTTP 200. Keep the response lightweight.

Authentication

Callers authenticate to Standby URLs via:

• Bearer token (recommended): Authorization: Bearer <APIFY_TOKEN>
• Query parameter (fallback): ?token=<APIFY_TOKEN>

Input handling

Standby Actors receive per-request input via HTTP query parameters or request body — NOT via INPUT.json. The traditional input schema (input_schema.json) is used for Actor initialization/configuration only, not per-request data.

Complete examples

JavaScript / TypeScript (Express)

import { Actor, log } from 'apify';
import express from 'express';

await Actor.init();

const app = express();
app.use(express.json());
const port = Actor.config.get('containerPort');

// Readiness probe
app.get('/', (req, res) => {
    if (req.headers['x-apify-container-server-readiness-probe']) {
        return res.send('OK');
    }
    res.json({ status: 'Actor is running in Standby mode' });
});

// Example endpoint
app.get('/search', (req, res) => {
    const { query } = req.query;
    log.info('Handling search request', { query });
    // ... handle request ...
    res.json({ results: [] });
});

app.listen(port, () => log.info(`Listening on port ${port}`));

Python (FastAPI)

from apify import Actor
import uvicorn
from fastapi import FastAPI, Request

app = FastAPI()

@app.get('/')
async def root(request: Request):
    if 'x-apify-container-server-readiness-probe' in request.headers:
        return {'status': 'OK'}
    return {'status': 'Actor is running in Standby mode'}

@app.get('/search')
async def search(query: str):
    Actor.log.info('Handling search request', extra={'query': query})
    # ... handle request ...
    return {'results': []}

async def main():
    async with Actor:
        port = Actor.config.container_port
        server = uvicorn.Server(uvicorn.Config(app, host='0.0.0.0', port=port))
        await server.serve()

if __name__ == '__main__':
    import asyncio
    asyncio.run(main())

Rules

• NEVER disable standby mode (usesStandbyMode: false) in .actor/actor.json without explicit user permission
• NEVER call `Actor.exit()` after handling a request — the server must stay alive
• ALWAYS listen on the SDK-provided port, not a hardcoded value
• ALWAYS implement the readiness probe at GET /
• Standby Actor READMEs must document: available endpoints, HTTP methods, request/response schemas, authentication (Authorization: Bearer <token>), and example calls.

Testing

apify run does not simulate Standby mode. To test locally:

1. Start the HTTP server directly (e.g., node src/main.js or python src/main.py) 2. Test the readiness probe: curl -H "x-apify-container-server-readiness-probe: true" http://localhost:<port>/ 3. Send requests with curl/httpie to verify endpoints

Standby vs. container web server

Do not confuse these:

• Container web server (ACTOR_WEB_SERVER_URL): per-run unique URL, no load balancing, no auto-scaling. Useful for live view UIs during a run.
• Standby mode (ACTOR_STANDBY_URL): stable hostname, load-balanced across runs, auto-scaled based on traffic. Use this for production APIs.

Further reading

• Developing Actors using Standby mode
• Running Actors in Standby mode