Skip to main content
POST
/
v1
/
monitor
/
perplexity
Monitor Perplexity Responses
curl --request POST \
  --url https://api.cloro.dev/v1/monitor/perplexity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "What are the best laptops for programming?",
  "country": "US",
  "include": {
    "markdown": false
  }
}'
{
  "success": true,
  "result": {
    "text": "Based on current sources and information, here are the best laptops for programming...",
    "html": "<div class=\"perplexity-response\"><p>Based on current sources and information, here are the best laptops...</p></div>",
    "sources": [
      {
        "position": 1,
        "url": "https://techcrunch.com/laptops",
        "label": "TechCrunch",
        "description": "Latest laptop reviews and recommendations"
      }
    ],
    "markdown": "Based on current sources and information, here are the best laptops for programming..."
  }
}

​
Overview

The Perplexity endpoint allows you to extract structured data from Perplexity AI about your brand, products, or any topic across various regions. This endpoint processes your prompts through Perplexity and returns parsed responses with real-time sources & citations.

​
Request Parameters

​
Required Parameters

  • prompt (string): The prompt to send to Perplexity (1-10,000 characters)

​
Optional Parameters

  • country (string): Optional country/region code for localized data extraction. Defaults to "US"
  • include (object): Optional flags for including additional response formats
    • markdown (boolean): Include markdown-formatted response in the result. Defaults to false

​
Response Format Options

By default, all responses include both text and HTML formats. You can optionally include markdown:
ParameterDefaultDescriptionUse casesCost
include.markdownfalseInclude markdown-formatted response in the resultDocumentation, content integration3 credits

​
Example Usage

​
Basic Request

{
  "prompt": "What are the latest developments in quantum computing?"
}

​
Request with Markdown Format

{
  "prompt": "What are the best Python frameworks for web development in 2025?",
  "country": "US",
  "include": {
    "markdown": true
  }
}

​
Response Schema

All successful responses include these fields:
FieldTypeDescription
successbooleanAlways true for successful responses
result.textstringPerplexity’s response text
result.sourcesarrayArray of sources referenced in the response
result.htmlstringPerplexity’s response formatted in HTML (always included)
result.markdownstringPerplexity’s response formatted in Markdown (included when include.markdown is true)

​
Error Responses

The API returns standard HTTP status codes to indicate the success or failure of requests. All error responses follow a consistent format with an error object containing a code, message, details, and timestamp.

​
Status Codes

  • 200 - Success
  • 400 - Bad Request (validation error)
  • 401 - Unauthorized (authentication error)
  • 403 - Forbidden (insufficient permissions or credits)
  • 404 - Not Found (route not found)
  • 409 - Conflict (resource conflict)
  • 429 - Too Many Requests
  • 499 - Client Closed Request (request was canceled)
  • 500 - Internal Server Error
  • 502 - Bad Gateway (external service error)

​
Validation Errors

FieldErrorDescription
prompt”Prompt cannot be empty”Must be 1-10,000 characters
prompt”Prompt is too long”Exceeds 10,000 character limit
country”Invalid country code”Must be valid ISO 3166-1 alpha-2 code
include.markdown”Expected boolean”Must be true or false

​
Concurrency Information

Concurrency information is included in response headers:
  • X-Concurrent-Limit: Maximum number of concurrent requests allowed
  • X-Concurrent-Current: Current number of concurrent requests
  • X-Concurrent-Remaining: Number of remaining concurrent slots available

​
Credits System

This endpoint uses a credit-based billing system:
  • Base cost: 3 credits per request
  • Additional costs: +0 credits (markdown format is included at no extra charge)
Credit information is included in response headers:
  • X-Credits-Remaining: Number of credits remaining in your account
  • X-Credits-Charged: Number of credits charged for this request

​
Supported Country Codes

The API accepts ISO 3166-1 alpha-2 country codes for the country parameter to extract data from different regions. For a complete list of supported country codes, see the Countries endpoint. Common Examples:
  • US - United States
  • GB - United Kingdom
  • CA - Canada
  • AU - Australia
  • DE - Germany
  • FR - France
  • JP - Japan
  • CN - China
  • IN - India
  • BR - Brazil

​
Best Practices

​
Prompt Guidelines

  1. Real-time Information: Ask about current events, news, or trending topics for best results
  2. Research Questions: Frame prompts as research or information-gathering questions
  3. Source Quality: Perplexity excels at providing recent, well-sourced information

​
Implementation Guidelines

  1. Handle Real-time Sources: Process sources array to provide current web references
  2. Use Markdown: Enable markdown format when integrating with research tools or documentation
  3. Error Handling: Implement robust error handling for failed extraction requests
  4. Rate Limiting: Respect concurrency limits and implement proper retry logic
  5. Source Verification: Validate source URLs as they represent real-time web content

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request parameters for monitoring Perplexity responses

​
prompt
string
required

The prompt to send to Perplexity

Required string length: 1 - 10000
Example:

"What are the best laptops for programming?"

​
country
string
default:US

Optional country/region code for localized monitoring

Example:

"US"

​
include
object

Optional flags for including additional response formats

Response

successful Perplexity monitoring response

​
success
boolean
required
Example:

true

​
result
object
required

Perplexity response data