### ChatGPT Quick Start Source: https://docs.cloro.dev/ This example demonstrates how to use the cloro API to get a response from ChatGPT. You need to replace 'YOUR_API_KEY' with your actual API key. ```APIDOC ## POST /v1/monitor/chatgpt ### Description Sends a prompt to ChatGPT and returns the AI's response. ### Method POST ### Endpoint /v1/monitor/chatgpt ### Parameters #### Request Body - **prompt** (string) - Required - The question or instruction for ChatGPT. - **country** (string) - Optional - The country code to simulate the request from (e.g., "US"). ### Request Example ```json { "prompt": "What do you know about Acme Corp?", "country": "US" } ``` ### Response #### Success Response (200) - **response** (string) - The response from ChatGPT. - **sources** (array) - A list of sources used to generate the response. #### Response Example ```json { "response": "Acme Corp is a fictional company often depicted in cartoons, known for its elaborate and often dangerous contraptions. It is famously associated with the character Wile E. Coyote and his pursuit of the Road Runner.", "sources": [ { "url": "https://en.wikipedia.org/wiki/Acme_Corporation", "title": "Acme Corporation - Wikipedia" } ] } ``` ``` -------------------------------- ### POST /v1/monitor/chatgpt Source: https://docs.cloro.dev/introduction/quickstart Sends a prompt to the ChatGPT monitoring endpoint to track and analyze model responses. ```APIDOC ## POST /v1/monitor/chatgpt ### Description Sends a prompt to the ChatGPT monitoring service to track interactions and retrieve model outputs. ### Method POST ### Endpoint https://api.cloro.dev/v1/monitor/chatgpt ### Parameters #### Request Body - **prompt** (string) - Required - The text prompt to send to the model. - **country** (string) - Optional - The two-letter country code for regional monitoring. ### Request Example { "prompt": "What do you know about Acme Corp?", "country": "US" } ### Response #### Success Response (200) - **success** (boolean) - Indicates if the request was processed successfully. - **result** (object) - Contains the model response and metadata. - **text** (string) - The generated response text. - **sources** (array) - A list of sources used by the model. #### Response Example { "success": true, "result": { "text": "Acme Corp is a fictional corporation that appears in many cartoons.", "sources": [] } } ``` -------------------------------- ### GET /products/{productId} Source: https://docs.cloro.dev/api-reference/endpoint/monitor-copilot Retrieves detailed information for a specific product using its unique identifier. ```APIDOC ## GET /products/{productId} ### Description Retrieves detailed information for a specific product using its unique identifier. ### Method GET ### Endpoint /products/{productId} #### Path Parameters - **productId** (string) - Required - The unique identifier of the product. ### Response #### Success Response (200) - **images** (array) - Product images with titles and URLs. - **title** (string) - Image title. - **url** (string) - Image URL. - **specifications** (array) - Product specifications (e.g., Color, Size). - **displayName** (string) - Specification name. - **values** (array) - Available values (array of strings). - **tags** (array) - Product tags (array of strings). - **price** (object) - Product pricing information. - **amount** (number) - Price amount. - **currency** (string) - Currency code (optional). - **currencySymbol** (string) - Currency symbol. - **seller** (string) - Seller name. - **sellerLogoUrl** (string) - Seller logo URL. - **brandName** (string) - Product brand name. - **rating** (object) - Product rating information. - **value** (number) - Rating value. - **count** (integer) - Number of ratings. - **canTrackPrice** (boolean) - Whether price tracking is available. - **markdown** (string) - Copilot's response formatted in Markdown (included when include.markdown is true). #### Response Example ```json { "images": [ { "title": "Product Image 1", "url": "https://example.com/image1.jpg" } ], "specifications": [ { "displayName": "Color", "values": ["Red", "Blue"] } ], "tags": ["electronics", "gadget"], "price": { "amount": 99.99, "currency": "USD", "currencySymbol": "$" }, "seller": "Example Seller", "sellerLogoUrl": "https://example.com/logo.png", "brandName": "Example Brand", "rating": { "value": 4.5, "count": 150 }, "canTrackPrice": true, "markdown": "As an AI assistant, I can help you find great laptops for programming..." } ``` #### Error Responses - **ValidationError** (object) - **AuthenticationError** (object) - **ForbiddenError** (object) ``` -------------------------------- ### Example ChatGPT Response with Sources (JSON) Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt This JSON example demonstrates a successful response from the ChatGPT endpoint, including extracted text and a list of sources with metadata such as publication dates and footnote status. It showcases how to access detailed information about the references used by ChatGPT. ```json { "success": true, "result": { "text": "Here's what I found about AI recruiting tools...", "sources": [ { "position": 1, "url": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com", "label": "12 Best AI Recruiting Tools For HR in 2025", "description": "Discover the top AI recruiting tools that can help HR professionals streamline their hiring process...", "footnote": false, "datePublished": "May 22, 2025" }, { "position": 2, "url": "https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com", "label": "7 Best AI Recruiting Software for Hiring Managers in 2025", "description": "A comprehensive guide to the best AI recruiting software options available for hiring managers...", "footnote": false, "datePublished": "April 10, 2025" }, { "position": 3, "url": "https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com", "label": "10+ Best AI Recruiting Software for 2025: Expert Reviews + Pricing", "description": "Expert reviews and pricing information for the best AI recruiting software solutions...", "footnote": true } ] } } ``` -------------------------------- ### JSON Map Entry Structure and Example Usage Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt Defines the structure of a map entry, including fields like name, category, rating, and description. It also provides an example JSON payload for a prompt and the corresponding response containing map entries for businesses. ```json { "prompt": "What are the best coffee shops in San Francisco?", "model": "CHATGPT", "country": "US" } ``` ```json { "success": true, "result": { "text": "Here are some highly-rated coffee shops in San Francisco...", "map": [ { "name": "Blue Bottle Coffee", "category": "Coffee shop", "rating": 4.5, "review_count": 1234, "description": "Specialty coffee roaster known for their meticulous pour-over preparations", "directions_url": null, "website_url": "https://bluebottlecoffee.com", "phone_number": "+1-415-555-0123", "position": 1, "citations": null }, { "name": "Philz Coffee", "category": "Coffee shop", "rating": 4.7, "review_count": 2156, "description": " neighborhood coffee shop famous for their custom-blended coffee", "directions_url": null, "website_url": "https://philzcoffee.com", "phone_number": "+1-415-555-0456", "position": 2, "citations": null } ] } } ``` -------------------------------- ### JSON Citation Pill Structure and Example Usage Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt Explains the structure of citation pills, which are inline citations within ChatGPT responses. It includes example JSON for a prompt and the response containing text, markdown with links, and structured citation pill metadata. ```json { "prompt": "What is the best AI software?", "model": "CHATGPT", "country": "US" } ``` ```json { "success": true, "result": { "text": "**ChatGPT** — Most versatile for writing, reasoning, and general problem-solving.\n**Claude** — Strong focus on safety and ethical reasoning.", "markdown": "**ChatGPT** — Most versatile for writing, reasoning, and general problem-solving. [Top 10 Best AI Apps in 2025](https://www.top10.com/best-lists/best-ai-apps)\n**Claude** — Strong focus on safety and ethical reasoning. [Best AI Platforms Compared](https://www.godofprompt.ai/blog/best-ai)", "citationPills": [ { "url": "https://www.top10.com/best-lists/best-ai-apps", "label": "Top 10 Best AI Apps in 2025", "description": "A comprehensive guide to the best AI applications available today", "domain": "top10.com", "datePublished": "2025-01-15", "citationPillId": 0 }, { "url": "https://www.godofprompt.ai/blog/best-ai", "label": "Best AI Platforms Compared", "description": "Expert comparison of leading AI platforms and their capabilities", "domain": "godofprompt.ai", "datePublished": "2025-02-01", "citationPillId": 1 } ] } } ``` -------------------------------- ### Execute multi-page Google search with AI Overview Source: https://docs.cloro.dev/changelog Example request for the /v1/monitor/google endpoint, demonstrating how to scrape multiple pages and include AI-generated summaries in the response. ```json { "query": "best laptops for programming", "pages": 3, "country": "US", "include": { "aioverview": { "markdown": true } } } ``` -------------------------------- ### Example JSON for Shopping Cards Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt This JSON structure represents a response containing shopping card data. It includes details about products, their prices, merchants, and ratings, designed to be displayed as interactive shopping cards. ```json { "prompt": "What are the best sneakers under $100?", "model": "CHATGPT", "country": "US" } ``` ```json { "success": true, "result": { "text": "If you're shopping for good sneakers under $100, it's definitely doable...", "shoppingCards": [ { "tags": [ "stylish casual leather sneaker", "heritage retro leather sneaker", "canvas everyday skate-inspired" ], "products": [ { "title": "Adidas VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "featured_tag": "stylish casual leather sneaker", "merchant": "adidas + others", "image_urls": [ "https://images.openai.com/static-rsc-1/AY2CiYu1AtGyrY1sX2_dN8Y7naInL0DvIvB1GO-loo2SdZW-LiT6_5gDEgLFJhrM60Vxg2uSbf8tn6WWltaLtpeZkkaGxjwbTm0PlICUvbMwZhhJBABlb-kVVV8m8bYX01_WnkdZrLO2uKEKcYzx3dt1w-E_i-5S4Qarcvp8-hTIM49zkLoHoZcVobqOx8CrulkNdcAoTyegDV532upAMzt1gH7PhFfVVQGyuFsWS_1iaY7_M5qdiKhB01R02Btl" ], "id": "3250714974047560249", "rating": 4.7, "num_reviews": 10394, "offers": [ { "merchant_name": "adidas", "product_name": "Adidas Women's VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com", "price": "$57.00", "details": "In stock online and nearby, Delivery between Sat - Mon $4.99", "available": true, "checkoutable": false, "price_details": { "base": "$57.00", "total": "$57.00" }, "tag": { "text": "Best price" } }, { "merchant_name": "Macy's", "product_name": "Adidas Women's VL Court 3.0", "url": "https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla&utm_source=chatgpt.com", "price": "$60.00", "details": "In stock online and nearby, Free delivery between Fri - Mon", "available": true, "checkoutable": false, "price_details": { "base": "$60.00", "total": "$60.00" } } ], "rating_grouped_citation": { "title": "Adidas Women's VL Court 3.0", "url": "https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html", "supporting_websites": [ { "title": "Adidas Women's VL Court 3.0", "url": "https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla" } ] } } ] } ] } } ``` -------------------------------- ### Handle API Response with Null AI Overview Source: https://docs.cloro.dev/api-reference/endpoint/monitor-google Example of a successful API response where the AI Overview is unavailable, demonstrating how the system returns null for that specific field while providing other search data. ```json { "success": true, "result": { "organicResults": [], "peopleAlsoAsk": [], "relatedSearches": [], "aioverview": null } } ``` -------------------------------- ### GET /scrape/aioverview Source: https://docs.cloro.dev/api-reference/endpoint/monitor-google Retrieves AI Overview results for a specific query, supporting optional markdown formatting. ```APIDOC ## POST /scrape ### Description Retrieves the AI Overview section for a given query. Can be configured to return raw text or formatted markdown. ### Method POST ### Endpoint /scrape ### Request Body - **query** (string) - Required - The search term. - **include.aioverview.markdown** (boolean) - Optional - Whether to return the result in markdown format. ### Request Example { "query": "best laptops for programming", "include": { "aioverview": { "markdown": true } } } ### Response #### Success Response (200) - **result.aioverview.text** (string) - The AI generated answer. - **result.aioverview.sources** (array) - List of sources used by the AI. - **result.aioverview.markdown** (string) - Formatted markdown content. #### Response Example { "result": { "aioverview": { "text": "...", "markdown": "# AI Overview..." } } } ``` -------------------------------- ### Handle API Response with Search Queries Source: https://docs.cloro.dev/changelog Example of a successful API response containing the generated text and the list of search queries used by the model to formulate its answer. ```json { "success": true, "result": { "text": "The name \"Acme Corporation\" is used in various contexts...", "searchQueries": [ "What is Acme Corporation?", "Acme Corp company overview", "Acme Corporation products and services" ] } } ``` -------------------------------- ### Initiate Asynchronous Task via API Source: https://docs.cloro.dev/guides/making-requests Sends a POST request to the Cloro.dev async task endpoint to start a new job. Supports optional webhooks for notifications and requires an idempotency key for request tracking. ```bash curl -X POST "https://api.cloro.dev/v1/async/task" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "taskType": "CHATGPT", "idempotencyKey": "your-custom-identifier-123", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "What is the weather in New York?", "country": "US" } }' ``` ```javascript import axios from 'axios'; const apiKey = 'YOUR_API_KEY'; const url = 'https://api.cloro.dev/v1/async/task'; const data = { taskType: 'CHATGPT', idempotencyKey: 'your-custom-identifier-123', webhook: { url: 'https://your-app.com/webhook-handler', }, payload: { prompt: 'What is the weather in New York?', country: 'US', }, }; try { const response = await axios.post(url, data, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json', }, }); console.log(response.data); } catch (error) { console.error(error); } ``` ```python import requests api_key = 'YOUR_API_KEY' url = 'https://api.cloro.dev/v1/async/task' payload = { "taskType": "CHATGPT", "idempotencyKey": "your-custom-identifier-123", "webhook": { "url": "https://your-app.com/webhook-handler" }, "payload": { "prompt": "What is the weather in New York?", "country": "US" } } headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` -------------------------------- ### Receive Webhook Endpoint (Node.js and Python) Source: https://docs.cloro.dev/guides/making-requests Example server endpoints to receive and acknowledge webhook POST requests. It's recommended to process the payload asynchronously and immediately respond with a 200 OK status. ```javascript // Example: A simple server endpoint to receive the webhook app.post('/webhook-handler', (req, res) => { // It's best to process the result asynchronously console.log(req.body); // Immediately send a 200 OK to acknowledge receipt res.status(200).send(); }); ``` ```python # Example: A simple server endpoint to receive the webhook @app.route('/webhook-handler', methods=['POST']) def handle_webhook(): # It's best to process the result asynchronously print(request.json) # Immediately send a 200 OK to acknowledge receipt return ('', 200) ``` -------------------------------- ### Cloro API response structure Source: https://docs.cloro.dev/introduction/quickstart Displays the standard JSON response format returned by the Cloro API upon a successful monitoring request. It includes a success boolean and a result object containing the generated text and sources. ```json { "success": true, "result": { "text": "Acme Corp is a fictional corporation that appears in many cartoons.", "sources": [] } } ``` -------------------------------- ### GET /v1/countries Source: https://docs.cloro.dev/api-reference/endpoint/countries Retrieves a list of all supported ISO 3166-1 alpha-2 country codes. This endpoint can be filtered by model to get countries available for specific AI providers. ```APIDOC ## GET /v1/countries ### Description Returns a list of all supported ISO 3166-1 alpha-2 country codes. Can be filtered by model to get countries available for specific AI providers. ### Method GET ### Endpoint /v1/countries ### Parameters #### Query Parameters - **model** (string) - Optional - Filter countries available for a specific model. Enum: aimode, aioverview, chatgpt, copilot, gemini, google, grok, perplexity. Example: chatgpt ### Request Example ```json { "example": "GET /v1/countries?model=chatgpt" } ``` ### Response #### Success Response (200) - **Array of strings** (string) - List of supported country codes. Example: ["AF", "AX", "AL", "DZ", "AS"] #### Error Response (400) - **object** - Bad Request - Invalid model parameter. Example: {"success": false, "error": "Request validation failed", "details": [{"field": "model", "message": "Invalid model specified"}]} #### Error Response (401) - **object** - Unauthorized - Authentication error. Example: {"error": {"code": "MISSING_API_KEY", "message": "Missing or invalid API key", "timestamp": "2025-01-15T12:00:00.000Z"}} #### Error Response (404) - **object** - Not Found - Route not found. Example: {"error": {"code": "RESOURCE_NOT_FOUND", "message": "Route not found", "details": {"id": "/v1/invalid-endpoint"}, "timestamp": "2025-01-15T12:00:00.000Z"}} #### Error Response (500) - **object** - Internal Server Error. Example: {"success": false, "error": "Maximum retries exceeded"} or {"error": {"code": "INTERNAL_SERVER_ERROR", "message": "Internal server error", "timestamp": "2025-01-15T12:00:00.000Z"}} ``` -------------------------------- ### POST /copilot/query Source: https://docs.cloro.dev/api-reference/endpoint/monitor-copilot Sends a query to the Copilot service to retrieve AI-generated responses, including source citations and optional product shopping cards. ```APIDOC ## POST /copilot/query ### Description Sends a natural language query to the Copilot service. Supports localization and optional formatting flags for HTML, Markdown, and raw streaming responses. ### Method POST ### Endpoint /copilot/query ### Parameters #### Request Body - **query** (string) - Required - The search query string (1-10000 characters). - **country** (string) - Optional - Country/region code (default: US). - **include** (object) - Optional - Flags for additional response formats: - **html** (boolean) - Include URL to full HTML response. - **markdown** (boolean) - Include markdown-formatted response. - **rawResponse** (boolean) - Include raw streaming response events. ### Request Example { "query": "What are the best laptops for programming?", "country": "US", "include": { "html": true, "markdown": true } } ### Response #### Success Response (200) - **success** (boolean) - Indicates if the request was successful. - **result** (object) - The Copilot response data containing text, HTML URL, sources, and shopping cards. #### Response Example { "success": true, "result": { "text": "As an AI assistant, I can help you find great laptops for programming...", "html": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html", "sources": [ { "position": 1, "url": "https://docs.microsoft.com/", "label": "Microsoft Docs", "description": "Official development documentation" } ] } } ``` -------------------------------- ### Endpoint Pricing Overview Source: https://docs.cloro.dev/guides/pricing This section provides a summary of the base cost for each monitored endpoint and the additional credit costs for specific features. ```APIDOC ## Endpoint Pricing This table outlines the base cost for each monitored endpoint and the additional costs for specific features. ### Base Costs & Additional Features | Endpoint | Base Cost | Additional Features | | --------------------------------------------------------- | --------- | ------------------------------------- | | [ChatGPT](/api-reference/endpoint/monitor-chatgpt) | 5 credits | Additional features available | | [Gemini](/api-reference/endpoint/monitor-gemini) | 4 credits | Markdown & HTML format included | | [Copilot](/api-reference/endpoint/monitor-copilot) | 3 credits | Markdown format included | | [Grok](/api-reference/endpoint/monitor-grok) | 3 credits | Markdown format included | | [Perplexity](/api-reference/endpoint/monitor-perplexity) | 3 credits | Markdown format included | | [Google Search](/api-reference/endpoint/monitor-google) | 3 credits | AI Overview (+2), Multi-page (tiered) | | [AI Mode](/api-reference/endpoint/monitor-aimode) | 4 credits | Markdown format included | | [AI Overview](/api-reference/endpoint/monitor-aioverview) | 5 credits | Part of Google Search endpoint | ### Google Search Additional Features | Feature | Cost | | ----------------------------- | ------------- | | Base request (page 1) | 3 credits | | + AI Overview | +2 credits | | + 2-3 pages | +1 credit | | + 4-10 pages | +2 credits | | **10 pages with AI Overview** | **5 credits** | **Notes:** * HTML response is included at no additional cost when requested. * Page 1 is included in the base cost (3 credits). * **2-3 pages**: +1 credit total (not per page). * **4-10 pages**: +2 credits total (not per page). * Maximum 10 pages can be requested per request. ### ChatGPT Additional Features | Feature | Cost | | --------------------------------- | -------------------- | | Base request (web search enabled) | 5 credits | | + Raw response | +2 credits | | + Query fan-out | +2 credits | | Both raw response + query fan-out | +2 credits (total 7) | **Note**: The +2 credits for ChatGPT's raw response and query fan-out are inclusive - enabling either or both features adds a total of +2 credits. ``` -------------------------------- ### Credits System and Management Source: https://docs.cloro.dev/guides/pricing Information on how credits are deducted, how to check remaining credits, and where to manage your account and purchase more credits. ```APIDOC ## Credits System ### Credit Deduction * Credits are deducted when requests complete successfully. * Failed requests (4xx errors) do not consume credits. ### Response Headers Credit information is included in the response headers: * `X-Credits-Remaining`: Number of credits remaining in your account. * `X-Credits-Charged`: Number of credits charged for this request. ### Getting More Credits Manage your account credits in the [dashboard](https://dashboard.cloro.dev): * Top up your account credits. * Monitor usage and billing. * Upgrade to higher volume plans. * Get custom pricing for enterprise usage. For information about concurrency limits and rate management, see [Credits and Limits](/guides/credits-and-limits). ``` -------------------------------- ### GET /search/results Source: https://docs.cloro.dev/api-reference/endpoint/monitor-perplexity Retrieves structured search results including media, location, and travel data. ```APIDOC ## GET /search/results ### Description Returns a structured object containing media content, travel listings, and location data based on the search query. ### Method GET ### Endpoint /search/results ### Response #### Success Response (200) - **result.videos** (array) - Video content found in response - **result.images** (array) - Image content found in response - **result.hotels** (array) - Hotel listings (when travel intent detected) - **result.places** (array) - General places and locations - **result.related_queries** (array) - Suggested follow-up search queries - **result.search_model_queries** (array) - Internal search queries used to generate response #### Response Example { "result": { "videos": [{"title": "Example", "url": "http://example.com", "medium": "video"}], "hotels": [{"name": "Grand Hotel", "rating": 4.5, "lat": 45.0, "lng": -73.0}], "places": [{"name": "Central Park", "rating": 5.0, "lat": 40.7, "lng": -73.9}], "related_queries": ["best hotels in NYC"] } } ``` -------------------------------- ### POST /search Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt Submits a natural language prompt to the AI model to retrieve business listings and citation data. ```APIDOC ## POST /search ### Description Sends a query to the AI model to receive a response containing business map entries and citation metadata. ### Method POST ### Endpoint /search ### Parameters #### Request Body - **prompt** (string) - Required - The natural language question or search query. - **model** (string) - Required - The AI model to use (e.g., "CHATGPT"). - **country** (string) - Required - The ISO country code for localization. ### Request Example { "prompt": "What are the best coffee shops in San Francisco?", "model": "CHATGPT", "country": "US" } ### Response #### Success Response (200) - **success** (boolean) - Indicates if the request was successful. - **result** (object) - Contains the response text, map entries, and citation pills. #### Response Example { "success": true, "result": { "text": "Here are some highly-rated coffee shops...", "map": [ { "name": "Blue Bottle Coffee", "category": "Coffee shop", "rating": 4.5, "review_count": 1234, "description": "Specialty coffee roaster", "website_url": "https://bluebottlecoffee.com", "phone_number": "+1-415-555-0123", "position": 1 } ], "citationPills": [ { "url": "https://example.com", "label": "Source Name", "description": "Source description", "domain": "example.com", "datePublished": "2025-01-01", "citationPillId": 0 } ] } } ``` -------------------------------- ### GET /v1/async/task/{taskId} Source: https://docs.cloro.dev/changelog Retrieves the status and results of an asynchronous task initiated by the system. ```APIDOC ## GET /v1/async/task/{taskId} ### Description Polls the status of an asynchronous task. Use this endpoint if you did not provide a webhook URL or need to manually verify task completion. ### Method GET ### Endpoint /v1/async/task/{taskId} ### Parameters #### Path Parameters - **taskId** (string) - Required - The unique identifier returned when the async request was initiated. ### Response #### Success Response (200) - **status** (string) - Current status (e.g., "pending", "completed", "failed"). - **result** (object) - The task output if status is "completed". #### Response Example { "taskId": "abc-123", "status": "completed", "result": { "data": "..." } } ``` -------------------------------- ### POST /v1/monitor/aimode Source: https://docs.cloro.dev/api-reference/endpoint/monitor-aimode Endpoint to trigger AI Mode monitoring and extract structured insights based on a provided prompt. ```APIDOC ## POST /v1/monitor/aimode ### Description Extract structured data from AI Mode about your brand, products, or any topic across various regions. ### Method POST ### Endpoint https://api.cloro.dev/v1/monitor/aimode ### Parameters #### Request Body - **prompt** (string) - Required - The prompt to send to AI Mode ### Request Example { "prompt": "Analyze the sentiment of recent reviews for product X" } ### Response #### Success Response (200) - **X-Concurrent-Limit** (integer) - Maximum number of concurrent requests allowed - **X-Credits-Remaining** (integer) - Number of credits remaining in user account #### Response Example { "status": "success", "data": { "analysis": "..." } } ``` -------------------------------- ### GET /v1/async/task/{taskId} Source: https://docs.cloro.dev/api-reference/endpoint/get-task-status Fetch the status and result of an asynchronous task using its unique ID. ```APIDOC ## GET /v1/async/task/{taskId} ### Description Fetch the status and result of an asynchronous task. ### Method GET ### Endpoint /v1/async/task/{taskId} ### Parameters #### Path Parameters - **taskId** (string) - Required - The ID of the task to fetch. ### Request Example ```json { "example": "No request body for GET request" } ``` ### Response #### Success Response (200) - **task** (object) - Information about the task, including its ID, type, status, creation time, and idempotency key. - **credits** (object) - Information about credits, including credits to charge and credits charged. - **response** (object) - The full response object, present only when the task is COMPLETED or FAILED. #### Response Example ```json { "task": { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "taskType": "completion", "status": "COMPLETED", "createdAt": "2025-01-15T12:00:00.000Z", "idempotencyKey": "unique-key-123" }, "credits": { "creditsToCharge": 10, "creditsCharged": 10 }, "response": { "choices": [ { "message": { "role": "assistant", "content": "This is the AI response." } } ], "usage": { "promptTokens": 50, "completionTokens": 100, "totalTokens": 150 } } } ``` #### Error Responses - **401 Unauthorized** - Authentication error. See `AuthenticationError` schema. - **404 Not Found** - Task not found. See `NotFoundError` schema. - **500 Internal Server Error** - Server error. See `InternalError` schema. ``` -------------------------------- ### Price Details Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt Provides a detailed breakdown of the price for an offer. ```APIDOC ## Price Details ### Description Includes a detailed price breakdown for an offer. ### Fields - **base** (string) - Base product price - **total** (string) - Total price including any additional costs ``` -------------------------------- ### GET /v1/async/task/{taskId} Source: https://docs.cloro.dev/api-reference/endpoint/get-task-status Retrieves the current status and result of an asynchronous task by its unique identifier. ```APIDOC ## GET /v1/async/task/{taskId} ### Description Poll this endpoint to check the progress of an asynchronous task. Once a task reaches a COMPLETED or FAILED state, the response will include the full result object. Tasks are retained for 24 hours after completion. ### Method GET ### Endpoint https://api.cloro.dev/v1/async/task/{taskId} ### Parameters #### Path Parameters - **taskId** (string) - Required - The unique identifier of the task to retrieve. ### Request Example ```bash curl -X GET "https://api.cloro.dev/v1/async/task/b27a21e1-7c39-4aa2-a347-23e828c426f9" \ -H "Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef" ``` ### Response #### Success Response (200) - **task** (object) - Contains task metadata including id, taskType, status, createdAt, and idempotencyKey. - **credits** (object) - Details regarding credits charged for the task. - **response** (object) - Optional; included only when status is COMPLETED or FAILED, containing the task results. #### Response Example (COMPLETED) { "task": { "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9", "taskType": "CHATGPT", "status": "COMPLETED", "createdAt": "2025-11-10T15:00:00.000Z", "idempotencyKey": "your-unique-key" }, "credits": { "creditsToCharge": 10, "creditsCharged": 10 }, "response": { "model": "gpt-5-mini", "html": "...", "text": "...", "sources": [], "markdown": "..." } } ``` -------------------------------- ### GET /v1/countries Source: https://docs.cloro.dev/changelog Retrieve a list of supported countries for AI monitoring, with optional filtering by AI provider model. ```APIDOC ## GET /v1/countries ### Description Returns a list of countries available for specific AI providers. Use the model parameter to filter by provider. ### Method GET ### Endpoint /v1/countries ### Parameters #### Query Parameters - **model** (string) - Optional - Filter by provider: aimode, aioverview, chatgpt, copilot, gemini, google, or perplexity. ### Request Example curl "https://api.cloro.dev/v1/countries?model=chatgpt" ### Response #### Success Response (200) - **countries** (array) - List of available country codes. #### Response Example { "countries": ["US", "GB", "DE"] } ``` -------------------------------- ### POST /copilot/extract Source: https://docs.cloro.dev/api-reference/endpoint/monitor-copilot Extracts structured data, product information, and shopping cards from Microsoft Copilot queries. ```APIDOC ## POST /copilot/extract ### Description Queries Microsoft Copilot to retrieve structured data. This endpoint automatically performs web searches and can return shopping cards for Microsoft products, enterprise solutions, and development tools. ### Method POST ### Endpoint /copilot/extract ### Parameters #### Query Parameters - **include.markdown** (boolean) - Optional - Include markdown-formatted response. Defaults to false. - **include.rawResponse** (boolean) - Optional - Include raw streaming response events. Defaults to false. ### Request Example { "query": "Microsoft Surface Pro features", "include.markdown": true } ### Response #### Success Response (200) - **result.shoppingCards** (array) - Array of shopping card objects containing product details. - **result.markdown** (string) - Response formatted in Markdown (if requested). - **result.rawResponse** (array) - Array of Copilot's streamed response events (if requested). #### Response Example { "result": { "shoppingCards": [ { "type": "shoppingProducts", "layout": "Carousel", "products": [ { "name": "Surface Pro 9", "price": { "amount": 999.99, "currency": "USD", "currencySymbol": "$" }, "url": "https://example.com/surface-pro-9" } ] } ], "markdown": "# Surface Pro 9\nFeatures include..." } } ``` -------------------------------- ### Request AI Overview Data via JSON Source: https://docs.cloro.dev/api-reference/endpoint/monitor-google Demonstrates how to structure a request payload to include Google AI Overview data with markdown formatting enabled. ```json { "query": "best laptops for programming", "include": { "aioverview": { "markdown": true } } } ``` -------------------------------- ### Access Request Identifier Header Source: https://docs.cloro.dev/guides/making-requests Example of the X-Request-Id header returned by the API for debugging and support tracking. ```http X-Request-Id: b0864943-5d45-4796-bc64-f052661256f0 ``` -------------------------------- ### Handle Idempotency Error Response Source: https://docs.cloro.dev/guides/making-requests Example JSON response returned when an idempotency key has already been used for a previous request. ```json { "success": false, "error": { "code": "RESOURCE_ALREADY_EXISTS", "message": "Task already exists", "details": { "field": "idempotencyKey", "value": "abc12312233123441234451112322212222223" }, "timestamp": "2025-12-10T11:41:40.243Z" } } ``` -------------------------------- ### POST /chat/query Source: https://docs.cloro.dev/api-reference/endpoint/monitor-chatgpt Sends a natural language prompt to the AI model to retrieve shopping recommendations or structured entity data. ```APIDOC ## POST /chat/query ### Description Processes a user prompt to return AI-generated responses, including shopping cards for products or lists of extracted entities. ### Method POST ### Endpoint /chat/query ### Parameters #### Request Body - **prompt** (string) - Required - The natural language query. - **model** (string) - Required - The AI model identifier (e.g., "CHATGPT"). - **country** (string) - Required - ISO country code for localization. ### Request Example { "prompt": "What are the best sneakers under $100?", "model": "CHATGPT", "country": "US" } ### Response #### Success Response (200) - **success** (boolean) - Indicates if the request was successful. - **result** (object) - Contains the response text and optional 'shoppingCards' or 'entities' arrays. #### Response Example { "success": true, "result": { "text": "Here are some great options...", "shoppingCards": [ { "products": [ { "title": "Adidas VL Court 3.0", "price": "$57.00", "url": "https://www.adidas.com" } ] } ] } } ```