apify

# Apify Skill

Run any Apify Actor through a standardized workflow: search → validate → execute → collect results.

## Prerequisites

- `APIFY_TOKEN` env var, or a `config.json` with tokens (copy `config.json.example`)
- Python 3 with `requests` installed

## Workflow

### Step 1: Parse User Intent

Extract from the user's request:
- **Platform/target** (Instagram, TikTok, Reddit, etc.)
- **What to scrape** (posts, profiles, hashtags, comments, etc.)
- **Targets** (URLs, usernames, keywords)
- **Quantity/filters** (how many, time range, min likes, etc.)

### Step 2: Select Token

If user specifies a token name or the task maps to a specific account, use that. Otherwise use `default`.

Token can be provided via:
1. `--token` flag (highest priority)
2. `config.json` tokens map (by `--token-name`)
3. `APIFY_TOKEN` env var (fallback)

### Step 3: Search & Select Actor

Run the search script:

```bash
python3 scripts/search_actor.py "instagram scraper" --top 3
```

Output: ranked candidates with score, success rate, rating, pricing model.

**Quality filters (built into script):**
- `notice` = NONE (not deprecated)
- 30-day success rate ≥ 95%
- 30-day runs ≥ 1,000
- User rating ≥ 4.0

Pick the top-ranked candidate. If user has a preference or prior experience with a specific Actor, skip search.

### Step 4: Get Actor Schema & Build run_input

Fetch the Actor's documentation:

```bash
web_fetch https://apify.com/{actor_id}.md
```

Read the input schema section. Construct `run_input` JSON based on:
- The Actor's required/optional fields
- The user's targets and filters
- Sensible defaults from the documentation

**Do NOT ask the user to write JSON.** Build it from their natural language request.

### Step 5: Probe Test (Top 1 → Top 2 → Top 3 fallback)

Test with minimal input before committing to full run:

```bash
python3 scripts/apify_runner.py {actor_id} \
  --input '{...}' \
  --token {token} \
  --probe-only \
  --list-key {key}
```

The probe automatically uses the fi...