How to Build an Apify Actor in Python

An Apify Actor is a scraper packaged as a cloud product: it runs on Apify's infrastructure, takes typed input from a form, writes to a managed dataset, and can be scheduled, monetized, and monitored. After publishing 300+ of them, here's the anatomy that works.

The minimal Actor

Four files make a Python Actor:

my-actor/
├── main.py               # your scraper, wrapped in the Actor lifecycle
├── requirements.txt      # dependencies
├── Dockerfile            # usually 3 lines on Apify's Python base image
└── .actor/
    ├── actor.json        # name, version, metadata
    └── input_schema.json # typed inputs → auto-generated UI form

from apify import Actor

async def main():
    async with Actor:
        inp = await Actor.get_input() or {}
        query = inp.get("query", "default")
        for item in scrape(query):          # your existing logic
            await Actor.push_data(item)     # → managed dataset

That's the whole integration: read input, push records. Your existing scraping logic stays untouched.

The input schema is your product's UI

Apify renders input_schema.json as the form every user sees. This file decides whether people can use your Actor without reading anything:

• Give every field a title, description, and sensible default
• Use editors ("stringList" for URL lists, proxy editors for proxy config) instead of raw JSON where possible
• Prefill an example that works on the first run — first impressions are runs that succeed

Design the dataset like a deliverable

Users export your dataset straight to CSV or Excel, so flat, consistently-named fields beat nested cleverness. Push one record per logical item, keep field order stable across versions, and include the source URL on every row — users trust data they can spot-check.

What separates a listed Actor from a used one

• A README that sells and documents: what it collects, sample output, limits, and pricing examples.
• Reliability: Apify shows your success rate publicly. Retries, graceful handling of empty results, and honest failure messages keep it high (the portfolio average here is 96.3%).
• Issue response: the marketplace shows response time. Fast answers turn one-time users into subscribers.
• Maintenance: targets change; a monthly smoke-run across your Actors catches breakage before users do.

FAQ