cotera
Logo

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
  2. Navigate to Settings > 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).

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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