# Apify

> Search the Apify Store for actors (web scrapers, data extractors, automation tools), inspect their input schemas, run them, and retrieve results.

Source: https://cotera.co/docs/reference/tools/individual-tools/apify

---

**Authentication Type:** API Key
**Description:** Search the Apify Store for actors (web scrapers, data extractors, automation tools), inspect their input schemas, run them, and retrieve results.

***

## Authentication

To authenticate with Apify, you'll need an API token from your Apify account:

1. Sign up or log in at [Apify Console](https://console.apify.com/)
2. Navigate to **Settings** > [**Integrations**](https://console.apify.com/account/integrations) in your account
3. Copy your **API token** (or create a new one with a descriptive name)

You'll need to provide:

* **apiKey** `string`: Your Apify API token

> **Security tip:** Never reuse the same token across multiple services. You can create multiple tokens and set expiration dates for temporary access. If a token is compromised, rotate it in the Console (there is a 24-hour grace period for the old token).

***

## Actors

### Search Actors

Search the Apify Store for actors (web scrapers, data extractors, automation tools, and more). Actors using the rental pricing model (flat monthly fee) are automatically excluded from results.

**Operation Type:** Query (Read)

**Parameters:**

* **query** `string` (required): Search query for finding Apify actors
* **limit** `number` (nullable): Maximum number of results to return (default 10)

**Returns:**

* **actors** `array of objects`: List of matching actors
  * **actorId** `string`: The actor ID in `owner/name` format (use this to get details or run the actor)
  * **name** `string`: The actor name in `owner/name` format
  * **title** `string`: Human-readable title
  * **description** `string`: Short description of what the actor does
  * **pricingModel** `string`: Pricing model (`FREE`, `PAY_PER_EVENT`, or `PRICE_PER_DATASET_ITEM`)
  * **url** `string`: URL to the actor in Apify Store

**Example Usage:**

```json
{
  "query": "amazon product scraper",
  "limit": 5
}
```

***

### Get Actor Details

Get detailed information about an Apify actor including its full input schema, description, example input, and usage stats. Use this before running an actor to understand exactly what input fields it expects.

**Operation Type:** Query (Read)

**Parameters:**

* **actorId** `string` (required): The actor ID or name (e.g., `apify/web-scraper`). Use Search Actors to find actors first.

**Returns:**

* **id** `string`: The actor ID
* **name** `string`: The actor name
* **username** `string`: The actor owner username
* **title** `string`: Human-readable title
* **description** `string`: Short description
* **readmeSummary** `string` (nullable): LLM-generated summary of the actor readme, including what input the actor expects
* **pricingModel** `string`: Pricing model (`FREE`, `PAY_PER_EVENT`, `PRICE_PER_DATASET_ITEM`, or `FLAT_PRICE_PER_MONTH`). Do not run actors with `FLAT_PRICE_PER_MONTH` (rental model).
* **isPublic** `boolean`: Whether the actor is public
* **isDeprecated** `boolean`: Whether the actor is deprecated
* **url** `string`: URL to the actor in Apify Store
* **inputSchema** `object` (nullable): JSON schema defining the actor's input properties, their types, descriptions, and defaults. Use this to construct the correct input for Run Actor.
* **exampleRunInput** `object` (nullable): Example input for running this actor
  * **body** `string`: Example JSON input body
  * **contentType** `string`: Content type of the example input
* **defaultRunOptions** `object` (nullable): Default run configuration
  * **build** `string` (nullable): Default build tag
  * **timeoutSecs** `number` (nullable): Default timeout in seconds
  * **memoryMbytes** `number` (nullable): Default memory in MB
* **stats** `object` (nullable): Actor usage statistics
  * **totalRuns** `number`: Total number of runs
  * **totalUsers** `number`: Total number of users

**Example Usage:**

```json
{
  "actorId": "apify/web-scraper"
}
```

***

### Run Actor

Run an Apify actor with the specified input. The tool waits briefly for the run to complete and returns results if available. If the run does not finish in time, use Get Run to poll for completion.

**Operation Type:** Mutation (Write)

**Parameters:**

* **actorId** `string` (required): The actor ID or name (e.g., `apify/web-scraper`)
* **input** `object` (nullable): JSON input to pass to the actor. Use Get Actor Details to check the `inputSchema` for available fields.
* **maxWaitSeconds** `number` (nullable): Maximum time in seconds to wait for the run to finish (default 25, max 300). If the run does not complete in time, use Get Run to poll for results.

**Returns:**

* **runId** `string`: The unique ID of the actor run
* **status** `string`: Run status (`SUCCEEDED`, `RUNNING`, `FAILED`, etc.)
* **datasetId** `string` (nullable): ID of the default dataset for this run
* **keyValueStoreId** `string` (nullable): ID of the default key-value store for this run
* **output** `array`: Dataset items if the run completed, otherwise empty array

**Example Usage:**

```json
{
  "actorId": "apify/web-scraper",
  "input": {
    "startUrls": [{ "url": "https://example.com" }],
    "maxPagesPerCrawl": 10
  },
  "maxWaitSeconds": 30
}
```

> **Important:** Always use Get Actor Details first to check the `inputSchema` for available limit fields (e.g., `maxResults`, `maxPages`, `resultsLimit`, `maxItems`). Setting appropriate limits avoids unexpectedly large or expensive runs.

***

### Get Run

Check the status of an Apify actor run and retrieve results. Use this to poll for completion when a run does not finish within the initial wait time.

**Operation Type:** Query (Read)

**Parameters:**

* **runId** `string` (required): The run ID returned from Run Actor
* **waitForFinish** `number` (nullable): Maximum time in seconds to wait for the run to finish (default 25, max 300). The API returns immediately if the run has already completed.

**Returns:**

* **runId** `string`: The run ID
* **actorId** `string`: The actor that was run
* **status** `string`: Run status (`SUCCEEDED`, `RUNNING`, `FAILED`, `ABORTED`, `TIMED-OUT`, etc.)
* **datasetId** `string` (nullable): ID of the default dataset
* **keyValueStoreId** `string` (nullable): ID of the default key-value store
* **output** `array`: Dataset items if the run completed, otherwise empty array
* **startedAt** `string`: When the run started
* **finishedAt** `string` (nullable): When the run finished (null if still running)

**Example Usage:**

```json
{
  "runId": "abc123xyz",
  "waitForFinish": 25
}
```

***

## Common Use Cases

**Web Scraping & Data Extraction:**

* Search for specialized scrapers in the Apify Store (e.g., Amazon product scrapers, Google Maps extractors)
* Inspect the actor's input schema to understand required fields and limits
* Run the scraper with appropriate parameters and retrieve structured data

**Competitive Intelligence:**

* Scrape competitor websites, product listings, and pricing data
* Monitor review sites for brand mentions and sentiment
* Extract social media data for market research

**Lead Generation:**

* Extract business listings from directories and maps
* Scrape job postings to identify growing companies
* Collect contact information from public profiles and websites

**Content Monitoring:**

* Set up periodic scrapes of news sites and blogs
* Monitor product availability and price changes
* Track social media mentions and engagement metrics

**Long-Running Jobs:**

* For actors that take longer than 25 seconds, Run Actor returns with status `RUNNING`
* Use Get Run to poll for completion, passing `waitForFinish` to long-poll up to 300 seconds per request
* Once status is `SUCCEEDED`, the output array contains the dataset items