# Track Perplexity answers `POST https://api.answerline.dev/v1/monitor/perplexity` Get structured output from Perplexity AI on your brand, your products or any other topic, in many regions From $1.00 per 1,000 requests. Failed requests are free. Also runs as an async task of type `PERPLEXITY`. ## Body - `prompt` (string, required): Prompt submitted to Perplexity, up to 2,000 characters. A longer prompt is refused with a 400 that states its length. - `country` (string, required): Code of the country or region used to localize the response - `include` (object): Flags that add extra output formats to the response (optional) - `include.html` (boolean): A link to the answer's own public page on perplexity.ai, in `html`, to check the answer against. No extra cost. - `include.markdown` (boolean): Add a markdown version of the response to the result - `include.rawResponse` (boolean): Return the answer as normalized stream events. For the engine's answer as received, use `include.rawWire`. - `include.rawWire` (boolean): Return the engine's own response as received in result.rawWire: the answer stream, the rendered results pages or the RSS feed, without Gemini's detected location or ChatGPT's session tokens; null where it was not captured. Free. See https://answerline.dev/docs/output-formats#raw-wire - `include.screenshot` (boolean): Return a full-page PNG screenshot of the engine's page as it showed the finished answer, in result.screenshot: a link, or one link per results page on Google Search. On ChatGPT, Gemini, AI Mode, Google Search, Perplexity and Grok; other engines refuse it with a 400. Absent when the answer was read without a rendered page or its page was not available. Free. See https://answerline.dev/docs/output-formats#screenshots - `state` (string): US state code (e.g. "CA", "DC" included). Sent without a country, the request asks for the US; sent with any country other than "US", it is refused with a 400, uncharged. ChatGPT and Gemini answer as a person in that state sees it; every other engine accepts it and answers for the whole US, at the price of a request without it. provenance.requestedState reports the state asked. See https://answerline.dev/docs/coverage#states - `answerDepth` ("any" | "full" | "quick"): Accepted so existing requests stay valid; it does not change the answer or the price. Every engine writes one depth: Perplexity answers every request with its Quick Search answer, and provenance.answerDepth says quick. See https://answerline.dev/docs/engine-features/#answer-depth ## Returns - `result.text` (string): Text of Perplexity's answer - `result.html` (string): Present when include.html is true: the link to the answer's public page on perplexity.ai. - `result.sources` (object[]): Sources the response cites - `result.citationPills` (object[]): Citation pills that appear inline in the Perplexity answer. Every element pairs one pill with one source: a pill backed by N sources (bracketed groups like Perplexity's `[1][2][3]`) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Empty when the answer has no pills. - `result.markdown` (string): Perplexity's answer rendered as Markdown (present when include.markdown is true) - `result.related_queries` (string[]): Suggested searches to follow up with - `result.videos` (object[]): Videos that appear in the response - `result.images` (object[]): Image found in the response - `result.hotels` (object[]): Hotels listed when the query shows travel intent - `result.places` (object[]): The places Perplexity lists on its map for a local or lodging question (restaurants, shops, hotels), in its order. Absent when it shows no map. - `result.shopping_cards` (object[]): Product cards for shopping with full product details (present when the query shows shopping intent) - `result.search_model_queries` (string[]): Search queries the engine ran internally to build the response - `result.rawResponse` (object[]): The answer as normalized stream events (present when include.rawResponse is true). For the engine's answer as received, use include.rawWire. - `result.screenshot` (string): Present when include.screenshot is true: the link to the PNG screenshot of the answer's public page on perplexity.ai. - `result.links` (object[]): The links in the answer's text, in the order a reader meets them: one entry per web (http or https) link the answer shows, images and code aside, with the words it shows (text), where it goes (url), its domain and its 1-based position. Sources cited by pills are in citationPills; links to the same page appear in both when the answer does both. Empty when the text links nowhere. ## Responses - 200: Perplexity monitoring result (success) - 400: Bad Request - the request failed validation - 401: Unauthorized - authentication failed - 403: Forbidden - INSUFFICIENT_CREDITS: the balance does not cover this request - 404: Not Found - No such route, or the engine is paused - 409: Conflict - the resource is in a conflicting state - 429: Too Many Requests - the call could not start now (`CONCURRENT_LIMIT_EXCEEDED`), or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers. `RATE_LIMIT_EXCEEDED`, with `Retry-After`, is sent only when one address presented too many unknown keys - 499: Client Closed Request - the client cancelled the request - 500: Internal Server Error - 502: Bad Gateway - the engine failed ## Request curl: ```bash curl -X POST "https://api.answerline.dev/v1/monitor/perplexity" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"Which project management tools do agencies use?","country":"US"}' ``` TypeScript: ```ts import { Client } from "@answerline/sdk"; const client = new Client({ apiKey: process.env.API_KEY! }); const answer = await client.monitor.perplexity({ "prompt": "Which project management tools do agencies use?", "country": "US" }); ``` Python: ```python import os from answerline import Client with Client(os.environ["API_KEY"]) as client: answer = client.monitor.perplexity( prompt="Which project management tools do agencies use?", country="US", ) ``` ## Example responses 200: ```json { "success": true, "result": { "text": "According to recent sources, these are the strongest monitors for coding...", "html": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html", "sources": [ { "position": 1, "url": "https://techcrunch.com/laptops", "label": "TechCrunch", "description": "Recent tablet reviews and buying advice" }, { "position": 2, "url": "https://www.youtube.com/watch?v=example", "label": "Top Notebooks This Year", "description": "Hands-on test of coding laptops" }, { "position": 3, "url": "https://wired.com/programming-laptops", "label": "Wired", "description": "Guide to picking a laptop for coding" } ], "citationPills": [ { "label": "Top Developer Monitors 2026 — Wired", "citationPillId": 1, "url": "https://techcrunch.com/laptops", "domain": "techcrunch.com", "description": "Recent tablet reviews and buying advice", "position": 1 }, { "label": "Tom's Hardware Laptop Buying Guide", "citationPillId": 1, "url": "https://wired.com/programming-laptops", "domain": "wired.com", "description": "Guide to picking a laptop for coding", "position": 3 } ], "markdown": "According to recent sources, these are the strongest monitors for coding...", "related_queries": [ "safest areas to book accommodation in Lisbon", "best-reviewed boutique hotels in Lisbon below €250", "best-reviewed seafood tascas in Alfama" ], "videos": [ { "title": "Lisbon's top hotels, ranked | The Guardian", "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": "Lisbon's top hotels, ranked | The Guardian", "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": "Casa do Largo Porto Boutique 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": [ "Rua das Flores, 41, Porto 4050-265 Portugal" ], "phone": "+351 21 340 5600", "description": "Set just steps from the old harbour, in one of the most sought-after quarters of central Porto...", "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": "Jardim do Miradouro", "url": "https://www.tripadvisor.com/Restaurant_Review-g189158-d1520116-Reviews-Floresta_Das_Escadinhas-Lisbon_District_Central_Portugal.html", "rating": 4.8, "num_reviews": 3778, "phone": "(312) 600-6090", "description": "Industrial-chic pizzeria offering wood-fired pies & a bar with craft beer.", "address": [ "Carrer de Mallorca 401, Barcelona 08013 Spain" ], "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": "Brooks Ghost 16", "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": null, "price": "$140.00", "merchant_name": "Nike", "product_name": "Brooks Ghost 16 Running Shoes", "available": true, "price_details": {}, "original_price": null } ], "position": 1, "rating": 4.6, "original_price": "string", "description": "Lightweight support for long-distance road racing.", "variants": [ null ] } ] } ], "search_model_queries": [ "top places to eat and stay in lisbon" ], "rawResponse": [ null ], "screenshot": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/3f9a1c2e8b7d4a6f9e0c1b2a3d4e5f60/page-1.png", "links": [ { "position": 1, "text": "Nike Pegasus 42", "url": "https://www.nike.com/t/pegasus-42-mens-road-running-shoes", "domain": "nike.com" } ] } } ``` 400: ```json { "success": false, "error": "Request validation failed", "details": [ { "field": "prompt", "message": "Prompt must not be empty" } ] } ``` 502: ```json { "error": { "code": "EXTERNAL_SERVICE_ERROR", "message": "External service error: the service failed", "details": { "service": "CHATGPT" }, "timestamp": "2025-01-15T12:00:00.000Z" } } ```