> ## Documentation Index > Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Extract Perplexity > Extract structured data from Perplexity AI about your brand, products, or any topic across various regions ## 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 enabled** This 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: * **Shopping queries**: [Product information, pricing, and shopping cards](/api-reference/endpoint/perplexity/shopping-cards) * **Travel queries**: [Hotel listings and places](/api-reference/endpoint/perplexity/travel-and-places) * **Media queries**: [Videos and images](/api-reference/endpoint/perplexity/media) related to the search * **General queries**: Standard web search with sources and citations ## Request parameters Uses [common parameters](/guides/making-requests/sync#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. | Section | Description | | ------------------------------------------------------------------------- | ------------------------------------------------ | | [Sources](/api-reference/endpoint/perplexity/sources) | Source citations referenced in the response | | [Shopping cards](/api-reference/endpoint/perplexity/shopping-cards) | Product cards with pricing, ratings, and offers | | [Media](/api-reference/endpoint/perplexity/media) | Videos and images relevant to the query | | [Travel and places](/api-reference/endpoint/perplexity/travel-and-places) | Hotels and places when travel intent is detected | ## Response schema Includes [common response fields](/guides/making-requests/sync#common-response-fields) plus: ### Core response fields | Field | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------- | | `result.text` | string | Perplexity's response text | | `result.html` | string | Response formatted in HTML (included when `include.html` is true) | | `result.sources` | array | Array of [sources](/api-reference/endpoint/perplexity/sources) referenced in the response | | `result.markdown` | string | Response formatted in Markdown (included when `include.markdown` is true) | | `result.rawResponse` | array | Array of Perplexity's streamed response events (included when `include.rawResponse` is true) | | `result.shopping_cards` | array | [Shopping cards](/api-reference/endpoint/perplexity/shopping-cards) when shopping intent detected | | `result.videos` | array | [Videos](/api-reference/endpoint/perplexity/media) relevant to the query | | `result.images` | array | [Images](/api-reference/endpoint/perplexity/media) relevant to the query | | `result.hotels` | array | [Hotels](/api-reference/endpoint/perplexity/travel-and-places) when travel intent detected | | `result.places` | array | [Places](/api-reference/endpoint/perplexity/travel-and-places) when location intent detected | ### Additional response data | Field | Type | Description | | ----------------------------- | ----- | ------------------------------------------------------------ | | `result.related_queries` | array | Suggested follow-up search queries | | `result.search_model_queries` | array | Internal search queries (fan-outs) used to generate response | Each search model query (fan-out) includes: | Field | Type | Description | | -------- | ------ | -------------------------------- | | `query` | string | Actual search query used | | `engine` | string | Search engine type ("web", etc.) | | `limit` | number | Result 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. ## OpenAPI ````yaml api-reference/openapi.json POST /v1/monitor/perplexity openapi: 3.1.0 info: title: cloro description: API for monitoring AI responses across different providers and regions license: name: MIT version: 1.0.0 servers: - url: https://api.cloro.dev description: Production server security: - bearerAuth: [] paths: /v1/monitor/perplexity: post: summary: Monitor Perplexity Responses description: >- Extract structured data from Perplexity AI about your brand, products, or any topic across various regions operationId: monitorPerplexity requestBody: description: Request parameters for monitoring Perplexity responses content: application/json: schema: $ref: '#/components/schemas/PerplexityMonitorRequest' required: true responses: '200': description: successful Perplexity monitoring response headers: X-Concurrent-Limit: description: Maximum number of concurrent requests allowed schema: type: integer example: 10 X-Concurrent-Current: description: Current number of concurrent requests schema: type: integer example: 3 X-Concurrent-Remaining: description: Number of remaining concurrent slots available schema: type: integer example: 7 X-Credits-Remaining: description: Number of credits remaining in user account schema: type: integer example: 4 X-Credits-Charged: description: Number of credits charged for this request schema: type: integer example: 5 content: application/json: schema: $ref: '#/components/schemas/PerplexityMonitorResponse' '400': description: Bad Request - Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized - Authentication error content: application/json: schema: $ref: '#/components/schemas/AuthenticationError' '403': description: Forbidden - Insufficient permissions or credits content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Not Found - Route not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '409': description: Conflict - Resource conflict content: application/json: schema: $ref: '#/components/schemas/ConflictError' '429': description: Too Many Requests headers: X-Concurrent-Limit: description: Maximum number of concurrent requests allowed schema: type: integer example: 10 X-Concurrent-Current: description: Current number of concurrent requests schema: type: integer example: 11 X-Concurrent-Remaining: description: Number of remaining concurrent slots available schema: type: integer example: 0 X-Credits-Remaining: description: Number of credits remaining in user account schema: type: integer example: 4 X-Credits-Charged: description: Number of credits charged for this request schema: type: integer example: 0 content: application/json: schema: $ref: '#/components/schemas/ConcurrentLimitError' '499': description: Client Closed Request - Request was canceled content: application/json: schema: $ref: '#/components/schemas/CanceledError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalError' '502': description: Bad Gateway - External service error content: application/json: schema: $ref: '#/components/schemas/ExternalServiceError' components: schemas: PerplexityMonitorRequest: required: - prompt - country type: object properties: prompt: description: The prompt to send to Perplexity type: string minLength: 1 maxLength: 10000 example: What are the best laptops for programming? country: description: Country/region code for localized response type: string example: US include: description: Optional flags for including additional response formats type: object properties: html: description: Include a URL to the full HTML of the response type: boolean default: false example: true markdown: description: Include markdown-formatted response in the result type: boolean default: false example: true rawResponse: description: Include raw streaming response events type: boolean default: false example: true default: html: false markdown: false rawResponse: false additionalProperties: false state: $ref: '#/components/schemas/StateParameter' additionalProperties: false PerplexityMonitorResponse: required: - success - result type: object properties: success: type: boolean example: true result: description: Perplexity response data type: object properties: text: type: string description: Perplexity's response text example: >- Based on current sources and information, here are the best laptops for programming... html: type: string format: uri description: A URL to the full HTML of the response. example: >- https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html sources: type: array description: Array of sources referenced in the response items: type: object properties: position: type: number description: The position index of the source in the response example: 1 url: type: string description: The URL of the source example: https://example.com/article label: type: string description: The display label for the source example: Perplexity Search description: type: string description: A description of the source content example: Real-time web search results example: - 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: type: array description: >- Inline citation pills extracted from the Perplexity answer. Each entry is one (pill, source) pair: when a pill cites N sources (Perplexity's `[1][2][3]` bracketed groups), the array contains N entries sharing the same `citationPillId` but carrying per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. Omitted from `result` when the answer carries no pills. items: type: object required: - label - citationPillId - url - domain - position properties: label: type: string description: >- Per-source title from the sources rail (e.g. `"Best Programming Laptops 2026 — TechCrunch"`). Always present; may be an empty string when the rail has no title for this source — read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels. example: Best Programming Laptops 2026 — TechCrunch citationPillId: type: integer description: >- 1-based ordinal shared by all entries from the same chip. Group by `citationPillId` to reconstruct the visible chip; the per-source `label` differs across entries within a chip. example: 1 url: type: string description: Direct URL of the cited source. example: https://techcrunch.com/laptops domain: type: string description: Host extracted from `url`, for grouping and display. example: techcrunch.com description: type: string description: >- Source description from the sources rail when Perplexity ships one. Omitted when absent. example: Latest laptop reviews and recommendations position: type: integer description: >- 1-based position of this source in the sibling `result.sources` array. example: 1 example: - 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: type: string description: >- Perplexity's response formatted in Markdown (included when include.markdown is true) example: >- Based on current sources and information, here are the best laptops for programming... related_queries: type: array description: Suggested follow-up search queries items: type: string example: - best neighborhoods to stay in Lisbon - top-rated luxury hotels in Lisbon under €300 - highest-rated traditional Portuguese restaurants in Baixa videos: type: array description: Video content found in response items: $ref: '#/components/schemas/MediaItem' images: type: array description: Image content found in response items: $ref: '#/components/schemas/MediaItem' hotels: type: array description: Hotel listings (when travel intent detected) items: $ref: '#/components/schemas/HotelItem' places: type: array description: General places and locations items: $ref: '#/components/schemas/PlaceItem' shopping_cards: type: array description: >- Shopping product cards with detailed product information (when shopping intent detected) items: type: object properties: tags: type: array description: Optional category tags for the shopping card items: type: string example: - running - athletic products: type: array description: Array of product objects items: type: object properties: title: type: string description: Product name example: Nike Pegasus 41 id: type: string description: Product identifier example: nike-pegasus-41 url: type: string description: Product page URL example: https://www.nike.com/t/pegasus-41 price: type: string description: Current price example: $140.00 merchant: type: string description: Merchant name example: Nike available: type: boolean description: Whether the product is currently available example: true imageUrls: type: array description: Product image URLs items: type: string numReviews: type: number description: Number of reviews (0 when none) example: 1284 offers: type: array description: Shopping offers from individual merchants items: type: object properties: url: type: string description: Offer URL with Perplexity referral parameters price: type: string description: Offer price example: $140.00 merchant_name: type: string description: Merchant name example: Nike product_name: type: string description: Product name as listed by the merchant example: Nike Pegasus 41 Running Shoes available: type: boolean description: Whether the offer is in stock example: true price_details: type: object description: Detailed price breakdown properties: display_price: type: string description: Formatted display price example: $140.00 original_price: type: string nullable: true description: >- Original price before discount; null when not on sale example: null position: type: integer description: >- 1-indexed rank across all products in all shopping cards in the response (flat, not reset per card) example: 1 rating: type: number description: Product rating (0-5 scale) example: 4.6 original_price: type: string nullable: true description: >- Original price before discount; null when not on sale description: type: string description: Product description example: Responsive cushioning for daily training runs. variants: type: array description: Product variants (size, color, etc.) items: type: object search_model_queries: type: array description: Internal search queries used to generate response items: $ref: '#/components/schemas/SearchModelQuery' rawResponse: type: array description: >- Raw upstream provider stream captured during the request. Each item is one chunk from the provider's wire protocol (SSE event, batchexecute frame, etc.). Format is provider-specific, undocumented, and may change without notice — use it for debugging or to access data not yet surfaced in the structured fields above. items: {} ValidationError: type: object properties: success: type: boolean example: false error: type: string example: Request validation failed details: type: array items: type: object properties: field: type: string example: prompt message: type: string example: Prompt cannot be empty AuthenticationError: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY_FORMAT - INVALID_OR_EXPIRED_API_KEY example: MISSING_API_KEY message: type: string example: Missing or invalid API key timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' ForbiddenError: type: object properties: error: type: object properties: code: type: string enum: - INSUFFICIENT_PERMISSIONS - INSUFFICIENT_CREDITS example: INSUFFICIENT_PERMISSIONS message: type: string example: Insufficient permissions details: type: object properties: requiredScopes: type: array items: type: string example: - read:monitor - write:monitor required: [] timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' NotFoundError: type: object properties: error: type: object properties: code: type: string example: RESOURCE_NOT_FOUND message: type: string example: Route not found details: type: object properties: id: type: string example: /v1/invalid-endpoint timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' ConflictError: type: object properties: error: type: object properties: code: type: string example: RESOURCE_CONFLICT message: type: string example: Resource conflict timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' ConcurrentLimitError: type: object properties: error: type: object properties: code: type: string example: CONCURRENT_LIMIT_EXCEEDED message: type: string example: Concurrent limit exceeded details: type: object properties: limit: type: number example: 10 timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' CanceledError: type: object properties: success: type: boolean example: false error: type: string example: Request was canceled InternalError: type: object oneOf: - properties: success: type: boolean example: false error: type: string example: Maximum retries exceeded - properties: error: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: Internal server error timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' ExternalServiceError: type: object properties: error: type: object properties: code: type: string example: EXTERNAL_SERVICE_ERROR message: type: string example: 'External service error: OpenAI' details: type: object properties: service: type: string example: OpenAI timestamp: type: string format: date-time example: '2025-01-15T12:00:00.000Z' StateParameter: description: >- State code for sub-country geo-targeting (e.g., "CA"). Only valid with country "US". type: string example: CA minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ MediaItem: type: object description: Media content (video or image) found in response properties: title: type: string description: Media title example: Best hotels in Lisbon, reviewed | The Independent url: type: string description: Media URL example: >- https://www.independent.co.uk/travel/europe/portugal/lisbon/best-lisbon-portugal-hotels-b1987832.html thumbnail: type: string description: Thumbnail URL example: >- https://d2u1z1lopyfwlx.cloudfront.net/thumbnails/636fbd12-6dee-5f44-a76d-fe7f9cd20e40/75ce41cb-6767-5082-a330-ee97c5866886.jpg medium: type: string description: Media type enum: - video - image - map example: image source: type: string description: Source platform example: web image_width: type: number description: Original image width example: 5600 image_height: type: number description: Original image height example: 3733 thumbnail_width: type: number description: Thumbnail width example: 300 thumbnail_height: type: number description: Thumbnail height example: 200 HotelItem: type: object description: Hotel listing with detailed information properties: name: type: string description: Hotel name example: Corpo Santo Lisbon Historical Hotel url: type: string description: Hotel page URL example: >- https://www.tripadvisor.com/Hotel_Review-g189158-d12659702-Reviews-Corpo_Santo_Lisbon_Historical_Hotel-Lisbon_District_Central_Portugal.html rating: type: number description: Hotel rating (0-5) example: 4.9 num_reviews: type: number description: Number of reviews example: 4374 address: type: array description: Address lines items: type: string example: - Largo do Corpo Santo, 25, Lisbon 1200-129 Portugal phone: type: string description: Phone number example: +351 21 828 8000 description: type: string description: Hotel description example: >- Located next to the riverside area, in one of the prime areas of the Lisbon Center... image_url: type: string description: Main hotel image URL example: >- https://media-cdn.tripadvisor.com/media/photo-o/30/28/6c/86/caption.jpg images: type: array description: Additional hotel image URLs items: type: string lat: type: number description: Latitude example: 38.707397 lng: type: number description: Longitude example: -9.142318 price_level: type: string description: Price level indicator categories: type: array description: Hotel categories items: type: string example: - Hotel PlaceItem: type: object description: General place or location information properties: name: type: string description: Place name example: Floresta Das Escadinhas url: type: string description: Place page URL example: >- https://www.tripadvisor.com/Restaurant_Review-g189158-d1520116-Reviews-Floresta_Das_Escadinhas-Lisbon_District_Central_Portugal.html rating: type: number description: Place rating (0-5) example: 4.8 address: type: array description: Address lines items: type: string example: - Rua de Santa Justa N°3, Lisbon 1100-483 Portugal lat: type: number description: Latitude example: 38.712717 lng: type: number description: Longitude example: -9.136362 categories: type: array description: Place categories items: type: string example: - Healthy - Grill - Barbecue - Mediterranean - Portuguese - European map_url: type: string description: Map URL example: >- https://google.com/maps/?q=find+best+hotels+and+restaurants+in+lisbon&ll=38.720914,-9.147162&z=15 images: type: array description: Place image URLs items: type: string SearchModelQuery: type: object description: Internal search query used to generate response properties: query: type: string description: Actual search query used example: find best hotels and restaurants in lisbon engine: type: string description: Search engine type example: web limit: type: number description: Result limit example: 8 securitySchemes: bearerAuth: type: http scheme: bearer ````