# Perplexity Search Images Scraper (`searchapi/perplexity-search-images-scraper`) Actor

Scrapes image results from Perplexity's image search. Extracts the canonical image schema: title, alt text, full image URL, thumbnail, dimensions, aspect ratio, format, source attribution, license, and citation context.

- **URL**: https://apify.com/searchapi/perplexity-search-images-scraper.md
- **Developed by:** [Search API](https://apify.com/searchapi) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 3 total users, 1 monthly users, 32.1% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.99 / 1,000 search results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Perplexity Search Images Scraper

Search Perplexity's public Images view with one query or a batch of queries. The Actor captures Perplexity's structured `media_items` response when available, uses the rendered page as a fallback, normalizes the records, and removes duplicates across the run.

### Input

- `mode`: `single` or `batch`.
- `query`: one image-search query. In batch mode it is included first when supplied.
- `queries`: additional queries for batch mode.
- `maxItems`: global record limit across all queries (1–500).
- `maxPages`: image-result batches loaded per query (1–5).
- `includeInlineAnswerImages`: include usable images rendered in the answer as a DOM fallback.
- `language` and `country`: align locale and browser fingerprint settings.
- `maxConcurrency`, retry, navigation, result-wait, and handler timeout controls.
- `proxyConfiguration`: optional Apify or custom proxy configuration.

Example single query:

```json
{
  "mode": "single",
  "query": "northern lights photography",
  "maxItems": 10,
  "maxPages": 1,
  "language": "en-US",
  "country": "US",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

Example batch:

```json
{
  "mode": "batch",
  "queries": [
    "northern lights photography",
    "Eiffel Tower night photography"
  ],
  "maxItems": 20,
  "maxConcurrency": 1
}
```

### Output

Every stored record includes a stable `id`, position, query, full image URL, thumbnail, title, result type, page, search engine, and scrape timestamp. When Perplexity supplies them, records also contain the source page/domain, source title, dimensions, aspect ratio, pixel count, format, MIME type, orientation, creator/license fields, and extraction metadata.

Unavailable optional fields are omitted instead of stored as `null` or empty strings. Raw API payloads, cookies, tokens, authorization data, and challenge pages are never stored.

### Proxy guidance

Direct access is the current working default. Perplexity may reject some proxy exit pools; a US Residential test returned HTTP 403 while a direct Apify Cloud run succeeded. Proxy support remains available for users whose target geography or network requires it. Keep `maxConcurrency` at 1 for anonymous public searches unless higher concurrency has been validated for your environment.

### Failure behavior

- HTTP status and content type are validated before HTML or JSON processing.
- Malformed and unexpected API payloads are rejected safely.
- Explicit Cloudflare challenges, CAPTCHA pages, and sign-in requirements are classified as `TARGET_BLOCKED`, are not retried, and do not create dataset records.
- A genuine “No images match this query” response completes with an empty dataset.
- Temporary browser, proxy, rate-limit, and server failures use bounded retries.

The Actor does not solve CAPTCHAs or bypass authentication and other access controls.

# Actor input Schema

## `mode` (type: `string`):

Use Single query for one search or Batch for multiple independent searches.

## `query` (type: `string`):

Required in Single mode and optionally included first in Batch mode.

## `queries` (type: `array`):

Additional image-search queries used in Batch mode.

## `maxItems` (type: `integer`):

Global maximum across all queries.

## `maxPages` (type: `integer`):

Maximum result batches to load with Perplexity's View more control.

## `includeInlineAnswerImages` (type: `boolean`):

Also include usable images rendered in the answer when the dedicated Images tab is unavailable or incomplete.

## `language` (type: `string`):

BCP-47 locale such as en-US, en-GB, de-DE, or fr-FR.

## `country` (type: `string`):

Two-letter code used to align Residential proxy location with the browser locale.

## `maxConcurrency` (type: `integer`):

Queries processed in parallel. Keep 1 for anonymous public searches; higher values may trigger Perplexity rate controls.

## `maxRequestRetries` (type: `integer`):

Retries temporary navigation, browser, proxy, rate-limit, and server failures. Explicit challenges are not retried.

## `navigationTimeoutSecs` (type: `integer`):

Maximum seconds for initial navigation.

## `resultsWaitSecs` (type: `integer`):

Maximum seconds to wait for an image API response, cards, an empty state, or a block signal.

## `requestHandlerTimeoutSecs` (type: `integer`):

Maximum seconds for one query including pagination.

## `proxyConfiguration` (type: `object`):

Proxy use is optional. Perplexity may reject some proxy pools, so the current working default is direct access; custom and Apify proxy settings remain supported.

## `debug` (type: `boolean`):

Log classifications and counts without logging response bodies, cookies, tokens, or signed URLs.

## Actor input object example

```json
{
  "mode": "single",
  "query": "northern lights photography",
  "queries": [],
  "maxItems": 50,
  "maxPages": 2,
  "includeInlineAnswerImages": true,
  "language": "en-US",
  "country": "US",
  "maxConcurrency": 1,
  "maxRequestRetries": 1,
  "navigationTimeoutSecs": 45,
  "resultsWaitSecs": 25,
  "requestHandlerTimeoutSecs": 90,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "debug": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "single",
    "query": "northern lights photography",
    "queries": [],
    "maxItems": 50,
    "maxPages": 2,
    "includeInlineAnswerImages": true,
    "language": "en-US",
    "country": "US",
    "maxConcurrency": 1,
    "maxRequestRetries": 1,
    "navigationTimeoutSecs": 45,
    "resultsWaitSecs": 25,
    "requestHandlerTimeoutSecs": 90,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("searchapi/perplexity-search-images-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "single",
    "query": "northern lights photography",
    "queries": [],
    "maxItems": 50,
    "maxPages": 2,
    "includeInlineAnswerImages": True,
    "language": "en-US",
    "country": "US",
    "maxConcurrency": 1,
    "maxRequestRetries": 1,
    "navigationTimeoutSecs": 45,
    "resultsWaitSecs": 25,
    "requestHandlerTimeoutSecs": 90,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("searchapi/perplexity-search-images-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "single",
  "query": "northern lights photography",
  "queries": [],
  "maxItems": 50,
  "maxPages": 2,
  "includeInlineAnswerImages": true,
  "language": "en-US",
  "country": "US",
  "maxConcurrency": 1,
  "maxRequestRetries": 1,
  "navigationTimeoutSecs": 45,
  "resultsWaitSecs": 25,
  "requestHandlerTimeoutSecs": 90,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call searchapi/perplexity-search-images-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,searchapi/perplexity-search-images-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/RgEZiMb8MjT7n7KIc/builds/O0wLW3AytPtDxLHJN/openapi.json