# Perplexity Search API: Answers, Sources & Citations in Bulk (`nerolabs/perplexity-search-api`) Actor

Perplexity answers with numbered citations, source domains and brand checks from Perplexity's official Sonar API. Inputs: questions, fileUrl (CSV or Google Sheet), datasetId, model, brands, domains, competitors, monitor. Charged per answer returned. Agent-ready: x402, MCP.

- **URL**: https://apify.com/nerolabs/perplexity-search-api.md
- **Developed by:** [Adam Pearce](https://apify.com/nerolabs) (community)
- **Categories:** AI, SEO tools, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $14.00 / 1,000 perplexity answers

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Perplexity Search API: Answers, Sources & Citations in Bulk

Need Perplexity's answer to hundreds of questions, with every source it cited, in a spreadsheet? Paste your questions (or a CSV, Google Sheet or dataset) and get back Perplexity's full answer, its numbered citations with domains, and, if you want, whether your brand and your competitors were named and where your website was cited.

It uses **Perplexity's official Sonar API**, so there is no browser, no login, no proxy and no captcha. A typical answer comes back in 3 to 8 seconds.

### What you can use it for

- **AI search visibility (GEO / AEO):** does Perplexity name your brand for "best CRM for a small business"? In what position, next to which competitors, and does it cite your site?
- **Brand and competitor tracking:** turn on monitor mode and schedule it weekly to see which citations and brand mentions appeared or dropped since the last run.
- **Research in bulk:** ask 500 questions from a Google Sheet and get answers plus sources as rows, ready for Excel, an LLM pipeline or a database.
- **Content and PR targets:** the summary ranks the domains Perplexity cites most for your topic, so you know which sites to get listed on.
- **AI agents:** an agent can call it through Apify's MCP server or x402 and get structured answers and citations back.

### Sample output (one row)

```json
{
  "question": "What is the best CRM for a small business?",
  "status": "ok",
  "answer": "For most small businesses, HubSpot CRM is a strong starting point because its free plan covers contacts, deals and email tracking [1][2]. Zoho CRM is cheaper as you grow [3], and Pipedrive suits sales-led teams [4]...",
  "citations": [
    { "position": 1, "url": "https://www.example-review-site.com/best-crm", "title": "The best CRM software", "domain": "example-review-site.com" },
    { "position": 2, "url": "https://www.hubspot.com/products/crm", "title": null, "domain": "hubspot.com" }
  ],
  "citedDomains": ["example-review-site.com", "hubspot.com"],
  "brandMentioned": true,
  "brandPosition": 1,
  "competitorsMentioned": ["Zoho", "Pipedrive"],
  "ownDomainsCited": [{ "domain": "hubspot.com", "position": 2, "url": "https://www.hubspot.com/products/crm" }],
  "model": "perplexity/sonar",
  "modelCostUsd": 0.0054,
  "monitorStatus": null
}
```

Every other column in your file or dataset is kept on the row.

The run's **Summary** (key-value store record `OUTPUT`) gives the share of answers that name your brand, the share that cite your site, competitors ranked by share of answers and average position, and the 30 most-cited domains.

### How much does it cost?

You pay two small amounts, both shown on your Apify bill:

1. **$0.02 per answer** to this Actor (less on higher Apify plans). Only answers that come back with text are charged. Failed, empty, duplicate and skipped rows are marked on the row and never charged.
2. **Perplexity's own model cost, about $0.005 per answer with Sonar**, billed to your Apify account by Apify's official OpenRouter proxy at OpenRouter's rate. Sonar Pro is about $0.01 to $0.02 per answer. On Apify's free plan, Apify charges the proxy cost at 10x.

So all-in, an answer costs about **$0.025**. For comparison, scraping the perplexity.com website costs around $0.20 an answer. Asking 1,000 questions a month costs about $25.

### Input

- **Questions**, or a **File or Google Sheet URL** (CSV, TSV, Excel, JSON), or an Apify **Dataset**. One question per row; the question column is detected (question, query, prompt, keyword) or set with *Question column*.
- **Perplexity model**: `sonar` (default) or `sonar-pro`.
- **Your brand names**, **Your website domains**, **Competitors**: all optional.
- **Source recency**: any, hour, day, week, month or year.
- **Country**: answer as a user in that country (or a `country` column per row).
- **Monitor mode**: remembers each question's last answer and marks new or dropped citations (`isNew` on each citation, `newCitations`, `droppedCitations`) and brand or competitor mentions gained or lost (`changes`). Use *Monitor name* to keep several monitors apart.

### Good to know

- Answers come from Perplexity's official Sonar API. That is the same search and models behind perplexity.com, but it is not a copy of the website, so the wording can differ a little from what you see on the site, and answers change from run to run.
- Brand and competitor mentions are found by exact whole-word matching in code, not guessed by an AI.
- Citations are listed in Perplexity's own order, so `position` matches the \[1], \[2] numbers in the answer text.
- About 5 questions are asked at a time, with automatic retries.

### FAQ

**Is this the same as the Perplexity website?** It uses the same Sonar models and web search through Perplexity's official API, but it is not a screenshot of the site. For tracking how Perplexity talks about a brand across many questions, the API is the stable, repeatable source.

**Do I need a Perplexity API key?** No. The model is called through Apify's own OpenRouter proxy with your run's Apify token, and its cost is added to your Apify bill.

**Can I track the same questions every week?** Yes: turn on monitor mode and schedule the Actor. Each run marks what changed since the one before.

If this saved you scraping Perplexity by hand, a review on the Apify Store helps a lot.

# Actor input Schema

## `questions` (type: `array`):

The questions or search queries to ask Perplexity, one per line. Each one returns Perplexity's full answer with its numbered citations and is charged once, only when an answer with text comes back. Or give a CSV, Google Sheet or dataset below instead.

## `fileUrl` (type: `string`):

A public link to a CSV, TSV, Excel, JSON or JSON Lines file with one question per row. A normal Google Sheets link works (share it as 'Anyone with the link can view'). Every other column is kept on the output row. Used when 'Questions' is empty.

## `datasetId` (type: `string`):

An Apify dataset with one question per row, for example a keyword list from another Actor. Every original column is kept. Use the picker rather than typing an ID. Used when 'Questions' and 'File or Google Sheet URL' are empty.

## `questionField` (type: `string`):

For a file or dataset: the column that holds the question. Leave empty to detect it (looks for question, query, prompt, keyword).

## `questionTemplate` (type: `string`):

Optional. Turns each row into a full question, for example 'Best CRM for {question}' with a row 'real estate agents'. {question} is replaced by the row's text. Useful when a sheet holds keywords, not questions.

## `fileFormat` (type: `string`):

Leave on auto unless the file is detected wrongly.

## `sheetName` (type: `string`):

For an Excel file: which sheet to read. Leave empty for the first sheet.

## `model` (type: `string`):

sonar is fast and cheap (about $0.005 of model cost per answer, billed to your Apify account by Apify's OpenRouter proxy). sonar-pro reads more sources and gives longer answers (about $0.01 to $0.02 of model cost per answer). Both are charged the same Actor price per answer.

## `brands` (type: `array`):

Optional. Your brand or product names, for example 'HubSpot'. Each answer reports brandMentioned and brandPosition (1 = named first among all your brands and competitors that appear).

## `domains` (type: `array`):

Optional. Your website domains, for example 'hubspot.com'. Each answer lists ownDomainsCited with the citation number Perplexity gave each one.

## `competitors` (type: `array`):

Optional. Competitor names or domains, for example 'Salesforce'. Each answer lists competitorsMentioned in the order named, and the summary ranks them by share of answers.

## `searchRecency` (type: `string`):

Optional. Ask Perplexity to use only sources from the last hour, day, week, month or year. Leave on 'any' for no limit.

## `searchContextSize` (type: `string`):

How much web content Perplexity reads per question. Low is the cheapest; medium and high cost a little more model fee.

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

Optional two-letter country code (US, GB, DE) to answer as a user in that country. A 'country' column in the file overrides it per row.

## `systemPrompt` (type: `string`):

Optional style instruction, for example 'Answer in 3 bullet points' or 'Answer in Spanish'. Perplexity follows it loosely and always answers the question itself; to change what is asked, use 'Question template'.

## `monitor` (type: `boolean`):

Remember each question's last answer (in a named key-value store) and, on the next run, mark only what changed: new and dropped citations (isNew on each citation), newly cited or dropped sites, and brand or competitor mentions gained or lost. Schedule the run daily or weekly. Off by default.

## `monitorName` (type: `string`):

Keeps separate monitors apart, for example one per client. Letters, numbers and dashes.

## `onlyChanged` (type: `boolean`):

In monitor mode, write only rows that are new or changed since the last run. Every answered question is still charged once, because Perplexity was asked.

## `keepOriginalFields` (type: `boolean`):

Copy every other column of the input row onto the output row.

## `concurrency` (type: `integer`):

How many questions are asked at the same time.

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

Stop after this many rows from the source.

## Actor input object example

```json
{
  "questions": [
    "What is the best CRM for a small business?",
    "HubSpot vs Salesforce for a startup",
    "Cheapest CRM with email automation"
  ],
  "fileFormat": "auto",
  "model": "sonar",
  "brands": [
    "HubSpot"
  ],
  "domains": [
    "hubspot.com"
  ],
  "competitors": [
    "Salesforce",
    "Pipedrive",
    "Zoho"
  ],
  "searchRecency": "any",
  "searchContextSize": "low",
  "monitor": false,
  "monitorName": "default",
  "onlyChanged": false,
  "keepOriginalFields": true,
  "concurrency": 5
}
```

# Actor output Schema

## `results` (type: `string`):

One row per question: Perplexity's answer, numbered citations with domains, brand and competitor checks, monitor changes. Your original columns are kept.

## `summary` (type: `string`):

Questions answered, model cost, brand share of answers, competitors ranked, most cited domains, monitor changes and warnings.

# 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 = {
    "questions": [
        "What is the best CRM for a small business?",
        "HubSpot vs Salesforce for a startup",
        "Cheapest CRM with email automation"
    ],
    "brands": [
        "HubSpot"
    ],
    "domains": [
        "hubspot.com"
    ],
    "competitors": [
        "Salesforce",
        "Pipedrive",
        "Zoho"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nerolabs/perplexity-search-api").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 = {
    "questions": [
        "What is the best CRM for a small business?",
        "HubSpot vs Salesforce for a startup",
        "Cheapest CRM with email automation",
    ],
    "brands": ["HubSpot"],
    "domains": ["hubspot.com"],
    "competitors": [
        "Salesforce",
        "Pipedrive",
        "Zoho",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("nerolabs/perplexity-search-api").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 '{
  "questions": [
    "What is the best CRM for a small business?",
    "HubSpot vs Salesforce for a startup",
    "Cheapest CRM with email automation"
  ],
  "brands": [
    "HubSpot"
  ],
  "domains": [
    "hubspot.com"
  ],
  "competitors": [
    "Salesforce",
    "Pipedrive",
    "Zoho"
  ]
}' |
apify call nerolabs/perplexity-search-api --silent --output-dataset

```

## MCP server setup

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

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/PKj3gk6EU9h1yIeC3/builds/nIGTheLw5eiT2DXZN/openapi.json
