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": {
    "html": false,
    "markdown": false,
    "rawResponse": false
  },
  "state": "CA"
}
'
{
  "success": true,
  "result": {
    "text": "Based on current sources and information, here are the best laptops for programming...",
    "html": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html",
    "sources": [
      {
        "position": 1,
        "url": "https://techcrunch.com/laptops",
        "label": "TechCrunch",
        "description": "Latest laptop reviews and recommendations"
      },
      {
        "position": 2,
        "url": "https://www.youtube.com/watch?v=example",
        "label": "Best Laptops 2026",
        "description": "Video review of programming laptops"
      },
      {
        "position": 3,
        "url": "https://wired.com/programming-laptops",
        "label": "Wired",
        "description": "Programming laptop buyer's guide"
      }
    ],
    "citationPills": [
      {
        "label": "Best Programming Laptops 2026 — TechCrunch",
        "citationPillId": 1,
        "url": "https://techcrunch.com/laptops",
        "domain": "techcrunch.com",
        "description": "Latest laptop reviews and recommendations",
        "position": 1
      },
      {
        "label": "Wired Laptop Buyer's Guide",
        "citationPillId": 1,
        "url": "https://wired.com/programming-laptops",
        "domain": "wired.com",
        "description": "Programming laptop buyer's guide",
        "position": 3
      }
    ],
    "markdown": "Based on current sources and information, here are the best laptops for programming...",
    "related_queries": [
      "best neighborhoods to stay in Lisbon",
      "top-rated luxury hotels in Lisbon under €300",
      "highest-rated traditional Portuguese restaurants in Baixa"
    ],
    "videos": [
      {
        "title": "Best hotels in Lisbon, reviewed | The Independent",
        "url": "https://www.independent.co.uk/travel/europe/portugal/lisbon/best-lisbon-portugal-hotels-b1987832.html",
        "thumbnail": "https://d2u1z1lopyfwlx.cloudfront.net/thumbnails/636fbd12-6dee-5f44-a76d-fe7f9cd20e40/75ce41cb-6767-5082-a330-ee97c5866886.jpg",
        "medium": "image",
        "source": "web",
        "image_width": 5600,
        "image_height": 3733,
        "thumbnail_width": 300,
        "thumbnail_height": 200
      }
    ],
    "images": [
      {
        "title": "Best hotels in Lisbon, reviewed | The Independent",
        "url": "https://www.independent.co.uk/travel/europe/portugal/lisbon/best-lisbon-portugal-hotels-b1987832.html",
        "thumbnail": "https://d2u1z1lopyfwlx.cloudfront.net/thumbnails/636fbd12-6dee-5f44-a76d-fe7f9cd20e40/75ce41cb-6767-5082-a330-ee97c5866886.jpg",
        "medium": "image",
        "source": "web",
        "image_width": 5600,
        "image_height": 3733,
        "thumbnail_width": 300,
        "thumbnail_height": 200
      }
    ],
    "hotels": [
      {
        "name": "Corpo Santo Lisbon Historical Hotel",
        "url": "https://www.tripadvisor.com/Hotel_Review-g189158-d12659702-Reviews-Corpo_Santo_Lisbon_Historical_Hotel-Lisbon_District_Central_Portugal.html",
        "rating": 4.9,
        "num_reviews": 4374,
        "address": [
          "Largo do Corpo Santo, 25, Lisbon 1200-129 Portugal"
        ],
        "phone": "+351 21 828 8000",
        "description": "Located next to the riverside area, in one of the prime areas of the Lisbon Center...",
        "image_url": "https://media-cdn.tripadvisor.com/media/photo-o/30/28/6c/86/caption.jpg",
        "images": [
          "<string>"
        ],
        "lat": 38.707397,
        "lng": -9.142318,
        "price_level": "<string>",
        "categories": [
          "Hotel"
        ]
      }
    ],
    "places": [
      {
        "name": "Floresta Das Escadinhas",
        "url": "https://www.tripadvisor.com/Restaurant_Review-g189158-d1520116-Reviews-Floresta_Das_Escadinhas-Lisbon_District_Central_Portugal.html",
        "rating": 4.8,
        "address": [
          "Rua de Santa Justa N°3, Lisbon 1100-483 Portugal"
        ],
        "lat": 38.712717,
        "lng": -9.136362,
        "categories": [
          "Healthy",
          "Grill",
          "Barbecue",
          "Mediterranean",
          "Portuguese",
          "European"
        ],
        "map_url": "https://google.com/maps/?q=find+best+hotels+and+restaurants+in+lisbon&ll=38.720914,-9.147162&z=15",
        "images": [
          "<string>"
        ]
      }
    ],
    "shopping_cards": [
      {
        "tags": [
          "running",
          "athletic"
        ],
        "products": [
          {
            "title": "Nike Pegasus 41",
            "id": "nike-pegasus-41",
            "url": "https://www.nike.com/t/pegasus-41",
            "price": "$140.00",
            "merchant": "Nike",
            "available": true,
            "imageUrls": [
              "<string>"
            ],
            "numReviews": 1284,
            "offers": [
              {
                "url": "<string>",
                "price": "$140.00",
                "merchant_name": "Nike",
                "product_name": "Nike Pegasus 41 Running Shoes",
                "available": true,
                "price_details": {
                  "display_price": "$140.00"
                },
                "original_price": null
              }
            ],
            "position": 1,
            "rating": 4.6,
            "original_price": "<string>",
            "description": "Responsive cushioning for daily training runs.",
            "variants": [
              {}
            ]
          }
        ]
      }
    ],
    "search_model_queries": [
      {
        "query": "find best hotels and restaurants in lisbon",
        "engine": "web",
        "limit": 8
      }
    ],
    "rawResponse": [
      "<unknown>"
    ]
  }
}

​
Overview

The Perplexity endpoint extracts structured data from Perplexity AI with real-time web sources. Beyond basic text responses, it automatically detects and extracts data objects including shopping products, media content, travel information, and location data based on query intent.
Web search enabledThis endpoint uses Perplexity’s default interface, which always performs web searches for all requests to provide real-time information with source citations.
The endpoint automatically detects different types of queries:

​
Request parameters

Uses common parameters. Endpoint-specific options:
  • include.rawResponse (boolean): Include raw streaming response events. Defaults to false

​
Response objects

The response includes the following sections. See each subpage for the full schema and examples.
SectionDescription
SourcesSource citations referenced in the response
Shopping cardsProduct cards with pricing, ratings, and offers
MediaVideos and images relevant to the query
Travel and placesHotels and places when travel intent is detected

​
Response schema

Includes common response fields plus:

​
Core response fields

FieldTypeDescription
result.textstringPerplexity’s response text
result.htmlstringResponse formatted in HTML (included when include.html is true)
result.sourcesarrayArray of sources referenced in the response
result.markdownstringResponse formatted in Markdown (included when include.markdown is true)
result.rawResponsearrayArray of Perplexity’s streamed response events (included when include.rawResponse is true)
result.shopping_cardsarrayShopping cards when shopping intent detected
result.videosarrayVideos relevant to the query
result.imagesarrayImages relevant to the query
result.hotelsarrayHotels when travel intent detected
result.placesarrayPlaces when location intent detected

​
Additional response data

FieldTypeDescription
result.related_queriesarraySuggested follow-up search queries
result.search_model_queriesarrayInternal search queries (fan-outs) used to generate response
Each search model query (fan-out) includes:
FieldTypeDescription
querystringActual search query used
enginestringSearch engine type (“web”, etc.)
limitnumberResult limit (typically 8)

​
Common questions

​
I’m getting 500 errors on certain prompts. What’s happening?

Perplexity occasionally classifies certain queries as “personal search” (queries with location context, first-person phrasing, or user-specific intent) and returns a 500 error. Mitigations:
  1. Remove in-prompt location injections — use the country request parameter instead of writing location into the prompt.
  2. Append "This is not a personal search." to affected prompts (reduces but does not eliminate failures; may slightly affect response quality).
  3. Build retry logic: Perplexity already retries internally 5–10 times, so persistent 500s after retries indicate a genuine personal-search classification.

​
How common are Perplexity shopping cards?

result.shopping_cards appear in fewer than 1 in 1,000 Perplexity responses (approximately 0.1% as of May 2026, compared to ~3.5% for ChatGPT and ~11% for Copilot). Do not build a workflow that depends on Perplexity returning shopping data.

​
I see [cite ] text in the response. Is that a bug?

No. Approximately 1% of Perplexity responses contain [cite ] placeholder text in result.text and result.markdown. This is an upstream Perplexity behavior — the platform occasionally emits a citation marker that doesn’t resolve to a URL. Strip or ignore [cite ] tokens in your post-processing.

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
required

Country/region code for localized response

Example:

"US"

​
include
object

Optional flags for including additional response formats

​
state
string

State code for sub-country geo-targeting (e.g., "CA"). Only valid with country "US".

Required string length: 2
Pattern: ^[A-Z]{2}$
Example:

"CA"

Response

successful Perplexity monitoring response

​
success
boolean
required
Example:

true

​
result
object
required

Perplexity response data