---
name: apify
label: Apify
version: 4
description: Run any Apify actor and return its dataset results. Use for web scraping, data extraction, and automation — TikTok, Twitter, Facebook, Instagram, YouTube, Google, and hundreds more. Authentication is handled automatically when configured in Settings → Integrations.
language: typescript
inputs:
  actor_id:
    type: string
    description: "Actor ID to run (format: owner~actor-name or owner/actor-name, e.g. 'novi~fast-tiktok-scraper', 'apify/twitter-scraper')"
  input:
    type: object
    description: Actor-specific input parameters as a JSON object (varies per actor)
    optional: true
  output_path:
    type: string
    description: File path to save JSON results to. When provided, the tool writes the dataset to this file and returns a summary instead of the raw JSON. Recommended for large datasets to avoid flooding the context.
    optional: true
  api_token:
    type: string
    description: Override the configured API token. Usually not needed — the token is provided automatically from Settings → Integrations → Apify.
    optional: true
    sensitive: true
  timeout_ms:
    type: number
    description: Max time to wait for actor completion in milliseconds (default 300000 = 5 min)
    optional: true
  poll_interval_ms:
    type: number
    description: How often to check run status in milliseconds (default 3000)
    optional: true
---

# Apify

Run any actor from the Apify Store, wait for completion, and return the dataset items as JSON.

## Authentication

The API token is resolved automatically:
1. `api_token` input parameter (explicit override)
2. `OFFICER_APIFY_TOKEN` environment variable (set automatically when configured in Settings → Integrations → Apify)

If neither is available, the tool returns an error prompting the user to configure the integration.

## Usage

Just provide the `actor_id` and optional `input`:
```
apify(actor_id: "novi~fast-tiktok-scraper", input: { type: "TREND", region: "PT", maxItems: 20 })
```

The tool starts the actor, polls until completion, fetches the dataset, and returns all items as JSON.

## Common Actors

| Actor | ID | Input example |
|-------|----|---------------|
| TikTok Scraper | `novi~fast-tiktok-scraper` | `{ type: 'TREND', region: 'US', maxItems: 20 }` |
| Twitter Scraper | `apify/twitter-scraper` | `{ searchTerms: ['#ai'], tweetsCount: 100 }` |
| Twitter User | `jupri/twitter-user-scraper` | `{ twitterUser: 'username', maxPosts: 50 }` |
| Facebook Scraper | `apify/facebook-scraper` | `{ startUrls: ['https://facebook.com/Page'], maxPostsPerPage: 50 }` |
| Facebook Search | `jupri/facebook-search-scraper` | `{ searchTerm: 'keyword', maxPosts: 30 }` |
| Instagram Hashtag | `apify/instagram-hashtag-scraper` | `{ hashtags: ['travel'], resultsLimit: 50 }` |
| Instagram User | `apify/instagram-user-scraper` | `{ usernames: ['natgeo'], resultsLimit: 50 }` |
| YouTube Scraper | `apify/youtube-scraper` | `{ searchTerms: ['tutorial'], maxResults: 20 }` |
| Google Search | `apify/google-search-scraper` | `{ queries: ['best restaurants lisbon'] }` |

## Error Handling

The tool returns clear error messages for:
- Missing API token → "Configure it in Settings → Integrations → Apify"
- API errors (401, 403, etc.) → includes the HTTP status and response body
- Actor failures → includes the actor's `statusMessage`
- Timeouts → reports the run ID and last known status

## Notes

- Actor IDs use `~` (Apify URL format) or `/` — both work
- Browse actors at https://apify.com/store
- Monitor usage and credits at https://console.apify.com/billing