openapi: 3.2.0
info:
  title: Cloro Dev Monitor API
  version: 1.0.0
  contact:
    name: cloro support
    email: support@cloro.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://cloro.dev/terms/
  description: 'Operations tagged Monitor across 2 of this provider''s published API definitions: cloro-dev-openapi.json, cloro-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cloro.dev
  description: Production server
security:
- bearerAuth: []
tags:
- name: Monitor
paths:
  /v1/monitor/chatgpt:
    post:
      summary: Monitor ChatGPT Responses
      description: Extract structured data from ChatGPT — answer text, cited sources, shopping cards, brand entities, and ads — for any prompt across supported regions
      operationId: monitorChatgpt
      requestBody:
        description: Request parameters for monitoring ChatGPT responses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatGPTMonitorRequest'
        required: true
      responses:
        '200':
          description: successful ChatGPT monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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: 1
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatGPTMonitorResponse'
        '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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/gemini:
    post:
      summary: Monitor Gemini Responses
      description: Extract structured data from Google Gemini — generated answer text and cited sources for any prompt, with Markdown and HTML export formats
      operationId: monitorGemini
      requestBody:
        description: Request parameters for monitoring Gemini responses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeminiMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Gemini monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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: 1
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeminiMonitorResponse'
        '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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/grok:
    post:
      summary: Monitor Grok Responses
      description: Extract structured data from Grok — answer text and cited sources, including X/Twitter references — for any prompt across supported regions
      operationId: monitorGrok
      requestBody:
        description: Request parameters for monitoring Grok responses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrokMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Grok monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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: 3
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrokMonitorResponse'
        '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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/google:
    post:
      summary: Monitor Google Search Results
      description: Extract structured data from Google Search including organic results, People Also Ask, related searches, and optional AI Overview
      operationId: monitorGoogle
      requestBody:
        description: Request parameters for monitoring Google search results
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Google monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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: 997
            X-Credits-Charged:
              description: Number of credits charged for this request
              schema:
                type: integer
                example: 3
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleMonitorResponse'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Forbidden - Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/google/goto:
    post:
      summary: Resolve a Google redirect link
      description: 'Resolve one Google redirect link to its destination URL. Send the `redirectLink` that ships beside every resolved link on a Google Search, Google News, or AI Mode response, and the response gives you the URL it points to.


        Charges no credits, does not use a concurrency slot, and counts against the per-second rate limit like any other call. Each request resolves one link, and Google gets at most 10 seconds to answer.'
      operationId: resolveGoogleGoto
      requestBody:
        description: The Google redirect link to resolve
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleGotoRequest'
        required: true
      responses:
        '200':
          description: The destination the redirect link points to
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleGotoResponse'
        '400':
          description: Bad Request - The url is missing, malformed, or is not a google.com /goto or /url link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '429':
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '502':
          description: Bad Gateway - Google did not answer with a redirect, or the request to Google failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalServiceError'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/google/news:
    post:
      summary: Monitor Google News Results
      description: Extract structured news articles from Google News including titles, links, snippets, sources, dates, and thumbnails
      operationId: monitorGoogleNews
      requestBody:
        description: Request parameters for monitoring Google News results
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleNewsMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Google News monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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: 997
            X-Credits-Charged:
              description: Number of credits charged for this request
              schema:
                type: integer
                example: 3
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleNewsMonitorResponse'
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Forbidden - Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/copilot:
    post:
      summary: Monitor Copilot Responses
      description: Extract structured data from Microsoft Copilot about your brand, products, or any topic across various regions
      operationId: monitorCopilot
      requestBody:
        description: Request parameters for monitoring Copilot responses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopilotMonitorRequest'
        required: true
      responses:
        '200':
          description: successful Copilot monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopilotMonitorResponse'
        '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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /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-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
  /v1/monitor/aimode:
    post:
      summary: Monitor AI Mode Responses
      description: Extract structured data from AI Mode about your brand, products, or any topic across various regions
      operationId: monitorAiMode
      requestBody:
        description: Request parameters for monitoring AI Mode responses
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiModeMonitorRequest'
        required: true
      responses:
        '200':
          description: successful AI Mode monitoring response
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 3
            X-Concurrency-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
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiModeMonitorResponse'
        '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 credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '429':
          description: Too Many Requests
          headers:
            X-Concurrency-Limit:
              description: Maximum number of concurrent requests allowed
              schema:
                type: integer
                example: 10
            X-Concurrency-Current:
              description: Current number of concurrent requests
              schema:
                type: integer
                example: 11
            X-Concurrency-Remaining:
              description: Number of remaining concurrent slots available
              schema:
                type: integer
                example: 0
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            X-Latency-Ms:
              $ref: '#/components/headers/XLatencyMs'
          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'
      tags:
      - Monitor
    servers:
    - url: https://api.cloro.dev
      description: Production server
components:
  schemas:
    CopilotMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Copilot response data
          type: object
          properties:
            text:
              type: string
              description: Copilot's response text
              example: As an AI assistant, I can help you find great laptops for programming...
            html:
              type: string
              format: uri
              description: A URL to the full HTML of the response.
              example: https://cdn.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: Microsoft Docs
                  description:
                    type: string
                    description: A description of the source content
                    example: Development hardware recommendations
              example:
              - position: 1
                url: https://docs.microsoft.com/
                label: Microsoft Docs
                description: Official development documentation
            citationPills:
              type: array
              description: 'Inline citation pills extracted from the Copilot answer. Each entry is one (pill, source) pair: when a pill cites N sources (consecutive citation events grouped into a single chip), 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 citation event (e.g. `"Microsoft 365 Documentation"`, `"Productivity Best Practices"`). Always present; may be an empty string when the event ships no title — read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.
                    example: Microsoft 365 Documentation
                  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://docs.microsoft.com/
                  domain:
                    type: string
                    description: Host extracted from `url`, for grouping and display.
                    example: docs.microsoft.com
                  description:
                    type: string
                    description: Source description from the sources rail when Copilot ships one. Omitted when absent.
                    example: Official development documentation
                  position:
                    type: integer
                    description: 1-based position of this source in the sibling `result.sources` array.
                    example: 1
              example:
              - label: Microsoft 365 Documentation
                citationPillId: 1
                url: https://docs.microsoft.com/
                domain: docs.microsoft.com
                description: Official development documentation
                position: 1
              - label: VS Code on GitHub
                citationPillId: 1
                url: https://github.com/microsoft/vscode
                domain: github.com
                description: Visual Studio Code repository
                position: 2
            shoppingCards:
              type: array
              description: Array of shopping/product cards extracted from the response (when available)
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Shopping card type
                    example: shoppingProducts
                  layout:
                    type: string
                    description: Layout style for the shopping card
                    example: Carousel
                  products:
                    type: array
                    description: Array of product information
                    items:
                      type: object
                      properties:
                        product:
                          type: object
                          description: Product identifier information
                          properties:
                            id:
                              type: string
                              description: Unique product ID
                            groupId:
                              type: string
                              description: Product group ID
                            brandGroupId:
                              type: string
                              description: Brand group ID (optional)
                        position:
                          type: integer
                          description: 1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).
                          example: 1
                        offerId:
                          type: string
                          description: Unique offer identifier
                        url:
                          type: string
                          description: Product page URL
                        name:
                          type: string
                          description: Product name
                        description:
                          type: string
                          description: Product description
                        images:
                          type: array
                          description: Product images with titles and URLs
                          items:
                            type: object
                            properties:
                              title:
                                type: string
                                description: Image title
                              url:
                                type: string
                                description: Image URL
                        specifications:
                          type: array
                          description: Product specifications (e.g., Color, Size)
                          items:
                            type: object
                            properties:
                              displayName:
                                type: string
                                description: Specification name
                              values:
                                type: array
                                description: Available values
                                items:
                                  type: string
                        tags:
                          type: array
                          description: Product tags
                          items:
                            type: string
                        price:
                          type: object
                          description: Product pricing information
                          properties:
                            amount:
                              type: number
                              description: Price amount
                            currency:
                              type: string
                              description: Currency code (optional)
                            currencySymbol:
                              type: string
                              description: Currency symbol
                        discountPrice:
                          type:
                          - object
                          - 'null'
                          description: Discount price, same shape as `price`. May be null or absent.
                          properties:
                            amount:
                              type: number
                              description: Price amount
                            currency:
                              type: string
                              description: Currency code (optional)
                            currencySymbol:
                              type: string
                              description: Currency symbol
                        seller:
                          type: string
                          description: Seller name
                        sellerLogoUrl:
                          type: string
                          description: Seller logo URL
                        brandName:
                          type: string
                          description: Product brand name
                        rating:
                          type: object
                          description: Product rating information
                          properties:
                            value:
                              type: number
                              description: Rating value
                            count:
                              type: integer
                              description: Number of ratings
                            maxRating:
                              type:
                              - number
                              - 'null'
                              description: Maximum rating scale. May be null or absent.
                        canTrackPrice:
                          type: boolean
                          description: Whether price tracking is available
            map:
              type: array
              description: Array of business/place map entries extracted from the response (when available)
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Business name
                    example: WonderWorks Pigeon Forge
                  position:
                    type: integer
                    description: Position in results (1-indexed)
                    example: 1
                  placeId:
                    type: string
                    description: Google Place ID
                    example: ChIJEYpTsk__W4gR2sQLGzOjE3o
                  location:
                    type: object
                    description: Business location
                    properties:
                      address:
                        type: string
                        description: Full street address
                        example: 100 Music Rd, Pigeon Forge, TN 37863
                      latitude:
                        type: number
                        description: GPS latitude
                        example: 35.823257
                      longitude:
                        type: number
                        description: GPS longitude
                        example: -83.5787498
                  phoneNumber:
                    type: string
                    description: Contact phone number
                    example: (865) 868-1800
                  url:
                    type: string
                    format: uri
                    description: Business website URL
                    example: http://www.wonderworksonline.com/pigeon-forge/
                  reviews:
                    type: array
                    description: Review aggregations from providers
                    items:
                      type: object
                      properties:
                        count:
                          type: integer
                          description: Number of reviews
                          example: 10625
                        rating:
                          type: number
                          description: Average rating
                          example: 4.3
                        providerName:
                          type: string
                          description: Review provider name
                          example: Google
                        providerIconUrl:
                          type: string
                          description: Provider icon URL
                        url:
                          type: string
                          format: uri
                          description: Reviews page URL
                          example: https://maps.google.com/?cid=8796553937077126362
                  photos:
                    type: array
                    description: Business photos
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: Photo URL
                        altText:
                          type: string
                          description: Alt text for the photo
                        providerName:
                          type: string
                          description: Photo provider name
                        providerUrl:
                          type: string
                          format: uri
                          description: Photo provider URL
                  openState:
                    type: string
                    description: Current open/closed status
                    example: Open · Closes 9 PM
                  category:
                    type: string
                    description: Business category
                    example: Amusement park
                  price:
                    description: Price level (if available)
                  layerLabel:
                    type: string
                    description: Map layer grouping label
                    example: Theme Parks
                example:
                  name: WonderWorks Pigeon Forge
                  position: 1
                  placeId: ChIJEYpTsk__W4gR2sQLGzOjE3o
                  location:
                    address: 100 Music Rd, Pigeon Forge, TN 37863
                    latitude: 35.823257
                    longitude: -83.5787498
                  phoneNumber: (865) 868-1800
                  url: http://www.wonderworksonline.com/pigeon-forge/
                  reviews:
                  - count: 10625
                    rating: 4.3
                    providerName: Google
                    providerIconUrl: null
                    url: https://maps.google.com/?cid=8796553937077126362
                  photos:
                  - url: https://lh3.googleusercontent.com/gps-cs-s/example
                    altText: null
                    providerName: null
                    providerUrl: https://maps.google.com
                  openState: Open · Closes 9 PM
                  category: Amusement park
                  price: null
                  layerLabel: Theme Parks
            searchQueries:
              type: array
              description: Array of query fan-out — the web search queries Copilot ran while generating the response. Automatically included when at least one is available, no surcharge.
              items:
                type: string
              example:
              - best laptops for programming 2025
              - developer laptop reviews
            markdown:
              type: string
              description: Copilot's response formatted in Markdown (included when include.markdown is true)
              example: As an AI assistant, I can help you find great laptops for programming...
            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: {}
    ProductResult:
      type: object
      description: One product cluster and its merchant offers. Only `title` is guaranteed; anything Google's panel lacks is omitted, never sent as `null`.
      required:
      - title
      properties:
        title:
          type: string
          description: Product cluster title, as Google displayed it. Empty when the page has no product heading.
          example: Apple iPhone 17
        stores:
          type: array
          description: Merchant offers. Always present on Google Search entries; omitted on AI Mode when Google lists none.
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
                description: Merchant name
                example: Apple
              link:
                type: string
                format: uri
                description: Merchant product URL, passed through from Google verbatim
                example: https://www.apple.com/shop/buy-iphone/iphone-17
              redirectLink:
                type: string
                description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
              price:
                type: object
                description: Offer price. Omitted when the displayed text can't be parsed.
                required:
                - value
                - currency
                properties:
                  value:
                    type: number
                    description: Parsed numeric price. On installment offers, the monthly payment.
                    example: 799
                  currency:
                    type: string
                    description: ISO 4217 code, or the displayed token when it maps to none
                    example: USD
                  raw:
                    type: string
                    description: Visible price text verbatim
                    example: $799.00
              installments:
                type: string
                description: Installment terms as displayed
              description:
                type: string
                description: Merchant's listing title, naming the exact SKU sold
                example: iPhone 17 256GB White - Apple
              buyingOptions:
                type: array
                description: Merchant badges in display order, such as stock status, delivery promise and returns window
                items:
                  type: string
              logo:
                type: string
                format: uri
                description: Merchant logo URL
              shipping:
                type: string
                description: Shipping cost or promise as displayed
              condition:
                type: string
                description: Item condition
                example: New
              rating:
                type: number
                description: Merchant rating
              reviews:
                type: string
                description: Merchant review count, abbreviated
                example: 2.3k
        aboutTheProduct:
          type: object
          description: Google's description of the product
          properties:
            description:
              type: string
              description: Prose blurb
            features:
              type: array
              description: Feature bullets, when shown
              items:
                type: string
        specifications:
          type: object
          description: 'Spec tables: each category name maps to key/value pairs. Category names and keys arrive in the response language.'
          additionalProperties:
            type: object
            additionalProperties:
              type: string
          example:
            general:
              Brand: Apple
              Storage: 256 GB
        images:
          type: array
          items:
            type: object
            required:
            - mainUrl
            properties:
              mainUrl:
                type: string
                format: uri
              thumbnailUrl:
                type: string
                format: uri
              title:
                type: string
        rating:
          type: number
          description: Product rating
        reviews:
          type: string
          description: Product review count
        variants:
          type: array
          description: Product variants Google offers
          items:
            type: object
        userReviews:
          type: array
          description: User reviews
          items:
            type: object
        relatedProducts:
          type: array
          description: Related products
          items:
            type: object
    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
    ChatGPTMonitorRequest:
      required:
      - prompt
      - country
      type: object
      properties:
        prompt:
          description: The prompt to send to ChatGPT
          type: string
          minLength: 1
          maxLength: 10000
          example: What do you know about Acme Corp?
        country:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        include:
          description: Optional flags for including additional response formats
          type: object
          default:
            html: false
            markdown: false
            rawResponse: false
            searchQueries: false
            ads: false
            shopping: false
          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 ChatGPT''s raw response payload. Paid add-on: one flat +2 credits covers any combination of `rawResponse`, `searchQueries`, `ads` and `shopping` ([pricing](/guides/providers#chatgpt-additional-features)).'
              type: boolean
              default: false
              example: true
            searchQueries:
              description: 'Include the query fan-out ChatGPT used to generate the response. Paid add-on: one flat +2 credits covers any combination of `rawResponse`, `searchQueries`, `ads` and `shopping` ([pricing](/guides/providers#chatgpt-additional-features)).'
              type: boolean
              default: false
              example: true
            ads:
              description: 'Include ads displayed in ChatGPT response. Paid add-on: one flat +2 credits covers any combination of `rawResponse`, `searchQueries`, `ads` and `shopping` ([pricing](/guides/providers#chatgpt-additional-features)).'
              type: boolean
              default: false
              example: true
            shopping:
              description: 'Include shopping cards and inline products with pricing and offers. Paid add-on: one flat +2 credits covers any combination of `rawResponse`, `searchQueries`, `ads` and `shopping` ([pricing](/guides/providers#chatgpt-additional-features)).'
              type: boolean
              default: false
              example: true
          required: []
          example:
            html: true
            markdown: true
            rawResponse: true
            searchQueries: true
            ads: true
            shopping: true
          additionalProperties: false
        legacy:
          description: 'Serve ChatGPT''s legacy desktop interface instead of the default mobile-web one. The legacy interface streams the answer as an event stream, so `result.model`, `result.searchQueries` and `result.mapSearchQueries` are populated. Best-effort and temporary: OpenAI controls which interface it serves and can retire the legacy one at any time, so a request can still come back in the mobile-web shape. Handle both. Defaults to false.'
          type: boolean
          default: false
          example: true
        disableWebSearch:
          description: 'Do not force ChatGPT''s web search. cloro returns the answer ChatGPT gives on its own, which uses web search only when ChatGPT decides to, so `result.sources`, `result.citationPills` and `result.searchQueries` are often empty. Defaults to false: web search is forced on every request.'
          type: boolean
          default: false
          example: true
        state:
          $ref: '#/components/schemas/StateParameter'
      additionalProperties: false
    HlParameter:
      description: Interface language, as Google's own `hl` parameter (e.g. `en`, `de`, `pt-BR`). Free-form and case-insensitive — Google owns the list of codes. Overrides the language cloro derives from the country, so the interface language and the result geography can differ.
      type: string
      example: en
    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 as Perplexity labels it, for example `video` or `image`
          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
    GrokMonitorRequest:
      required:
      - prompt
      - country
      type: object
      properties:
        prompt:
          description: The prompt to send to Grok
          type: string
          minLength: 1
          maxLength: 10000
          example: What are the best laptops for programming?
        country:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        include:
          description: Optional flags for including additional response formats
          type: object
          properties:
            markdown:
              description: Include markdown-formatted response in the result
              type: boolean
              default: false
              example: true
            html:
              description: Include HTML-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:
            markdown: false
            html: false
            rawResponse: false
          additionalProperties: false
        state:
          $ref: '#/components/schemas/StateParameter'
      additionalProperties: false
    GlParameter:
      description: Alternative to `country`, using Google's own parameter name for the result geography. Same ISO 3166-1 alpha-2 codes, accepted in either case (`us` or `US`), and must be a country the endpoint supports — see `GET /v1/countries`. Provide `country` or `gl`; sending both with different values is a `400`.
      type: string
      example: us
    GoogleNewsMonitorRequest:
      required:
      - query
      type: object
      properties:
        query:
          description: The search query to execute on Google News
          type: string
          minLength: 1
          maxLength: 10000
          example: climate change
        country:
          $ref: '#/components/schemas/CountryCode'
          description: ISO 3166-1 alpha-2 country code for localized news results. See [List of countries](/api-reference/endpoint/countries) for the codes each provider supports.
        gl:
          $ref: '#/components/schemas/GlParameter'
        hl:
          $ref: '#/components/schemas/HlParameter'
        device:
          description: Device the search is run from. 'desktop' returns the desktop news SERP; 'ios' (Safari on iPhone), 'android' (Chrome on Android) and 'mobile' (alias for 'android') all return the mobile news SERP.
          type: string
          enum:
          - desktop
          - mobile
          - ios
          - android
          default: desktop
          example: desktop
        pages:
          description: 'Number of news results pages to scrape (1-10). Paid add-on: +2 credits per page after the first ([pricing](/guides/providers#google-search-multi-page-pricing)).'
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          example: 1
        include:
          description: Optional flags for including additional response data
          type: object
          properties:
            html:
              description: Include raw HTML response from Google News
              type: boolean
              default: false
              example: false
          default:
            html: false
          additionalProperties: false
      additionalProperties: false
      anyOf:
      - required:
        - country
      - required:
        - gl
    RateLimitError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: RATE_LIMIT_EXCEEDED
            message:
              type: string
              example: API key rate limit exceeded
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ExternalServiceError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: EXTERNAL_SERVICE_ERROR
            message:
              type: string
              example: goto resolve request failed
            details:
              type: object
              properties:
                service:
                  type: string
                  example: google
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    GeminiMonitorRequest:
      required:
      - prompt
      - country
      type: object
      properties:
        prompt:
          description: The prompt to send to Gemini
          type: string
          minLength: 1
          maxLength: 10000
          example: Explain quantum computing
        country:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        include:
          description: Optional flags for including additional response formats
          type: object
          default:
            markdown: false
            html: false
            rawResponse: false
          properties:
            markdown:
              description: Include markdown-formatted response in the result
              type: boolean
              default: false
              example: true
            html:
              description: Include HTML-formatted response in the result
              type: boolean
              default: false
              example: true
            rawResponse:
              description: Include raw streaming response events
              type: boolean
              default: false
              example: true
          required: []
          example:
            markdown: true
            html: false
            rawResponse: false
          additionalProperties: false
        state:
          $ref: '#/components/schemas/StateParameter'
      additionalProperties: false
    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:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        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
    GrokMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Grok response data
          type: object
          properties:
            text:
              type: string
              description: Grok's response text
              example: Based on current information and real-time web search, here are excellent laptop options for programming...
            html:
              type: string
              format: uri
              description: A URL to the full HTML of the response.
              example: https://cdn.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html
            sources:
              type: array
              description: Array of sources referenced in the response with enhanced metadata
              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: Tech Source
                  description:
                    type: string
                    description: A description of the source content
                    example: In-depth laptop guide for developers
                  preview:
                    type: string
                    description: Preview text snippet from the source
                    example: When choosing a laptop for programming, consider RAM, processor, storage...
                  searchEngineText:
                    type: string
                    description: Search engine display text
                    example: Best Programming Laptops 2025
                  siteName:
                    type: string
                    description: Website name
                    example: Tech Reviews
                  metadataTitle:
                    type: string
                    description: Source metadata title
                    example: Complete Guide to Development Laptops
                  creator:
                    type: string
                    description: Content creator/author
                    example: John Doe
                  image:
                    type: string
                    format: uri
                    description: Source image URL
                    example: https://example.com/preview.jpg
                  favicon:
                    type: string
                    format: uri
                    description: Website favicon URL
                    example: https://example.com/favicon.ico
              example:
              - position: 1
                url: https://techcrunch.com/programming-laptops
                label: TechCrunch
                description: Best laptops for coding and development
                preview: When looking for a programming laptop, prioritize RAM and processor power...
                searchEngineText: Top Development Laptops 2025
                siteName: TechCrunch
                metadataTitle: Ultimate Guide to Programming Laptops
                creator: Tech Team
                image: https://techcrunch.com/preview.jpg
                favicon: https://techcrunch.com/favicon.ico
            searchQueries:
              type: array
              items:
                type: string
              description: Array of search queries Grok used to gather information for the response
              example:
              - best laptops for programming 2026
              - top developer laptops 2026
            model:
              type: string
              nullable: true
              description: The model identifier used to generate the response
              example: grok-4-auto
            markdown:
              type: string
              description: Grok's response formatted in Markdown (included when include.markdown is true)
              example: Based on current information and real-time web search, here are excellent laptop options for programming...
            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: {}
    GoogleMonitorRequest:
      anyOf:
      - required:
        - query
        - country
      - required:
        - query
        - gl
      - required:
        - url
      type: object
      properties:
        query:
          description: The search query to execute on Google. Required unless you supply 'url' instead — the two are mutually exclusive.
          type: string
          minLength: 1
          maxLength: 10000
          example: best laptops for programming
        url:
          description: A complete Google web search URL to run instead of building the request from 'query' and the targeting fields. Must be an absolute http(s) URL on a Google web search host (google.com, google.co.uk, www.google.de, ...), with the path '/search' and a non-empty 'q'. Mutually exclusive with 'query', 'location', 'uule' and 'pages' — the URL owns those values. cloro applies a fixed set of query parameters — 'q', 'gl', 'hl', 'uule', 'num' (read as result depth), 'start', 'tbs' and 'safe' — and drops anything else. URLs carrying 'tbm' are rejected, because they target a Google vertical with its own endpoint and pricing (use POST /v1/monitor/google/news for tbm=nws).
          type: string
          format: uri
          example: https://www.google.com/search?q=best+laptops+for+programming&hl=en&gl=us&num=30
        country:
          $ref: '#/components/schemas/CountryCode'
          description: ISO 3166-1 alpha-2 country code for localized search results. See [List of countries](/api-reference/endpoint/countries) for the codes each provider supports. Required in the standard request shape unless you send `gl`. When you supply 'url' instead, country is derived from the URL's 'gl' — pass it explicitly to override that, or when the URL has no 'gl'.
        gl:
          $ref: '#/components/schemas/GlParameter'
        hl:
          $ref: '#/components/schemas/HlParameter'
        location:
          description: 'Google canonical location name for geo-targeted results, in comma-separated format: ''City,Region,Country'' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside ''country'' for city-level precision. Mutually exclusive with ''uule'' — provide one or the other, not both. Cannot be combined with ''url''. When both `location` and `uule` are omitted, cloro pins results to the country''s canonical location (e.g. `Portugal` for `PT`) where it has one; otherwise Google geolocates from the proxy''s exit IP.'
          type: string
          example: New York,New York,United States
        uule:
          description: Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both. Cannot be combined with 'url'; put 'uule' in the URL's query string instead.
          type: string
          example: w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5
        device:
          description: Device the search is run from. 'desktop' returns the desktop SERP; 'ios' (Safari on iPhone), 'android' (Chrome on Android) and 'mobile' (alias for 'android') all return the mobile SERP.
          type: string
          enum:
          - desktop
          - mobile
          - ios
          - android
          default: desktop
          example: desktop
        pages:
          description: 'Number of search results pages to scrape (1-10). Paid add-on: +2 credits per page after the first ([pricing](/guides/providers#google-search-multi-page-pricing)). Cannot be combined with ''url'' — in that shape, depth comes from the URL''s ''num'' (rounded up to whole pages of 10, capped at 10 pages).'
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          example: 3
        include:
          description: Optional flags for including additional response data
          type: object
          properties:
            html:
              description: Include raw HTML response from Google search
              type: boolean
              default: false
              example: false
            aioverview:
              description: 'Include Google AI Overview in the response. Paid add-on: one flat +2 credits covers `aioverview` and `paaAioverview`, alone or together ([pricing](/guides/providers#google-search-multi-page-pricing)).'
              type: object
              properties:
                markdown:
                  description: Include AI Overview formatted as markdown
                  type: boolean
                  default: false
                  example: true
              default:
                markdown: false
              additionalProperties: false
            paaAioverview:
              description: 'Hydrate AI-Overview-type People Also Ask items with markdown content and sources. Paid add-on: one flat +2 credits covers `aioverview` and `paaAioverview`, alone or together ([pricing](/guides/providers#google-search-multi-page-pricing)). Each hydrated item adds one scraper fetch (typically 1-2 per page), so responses take longer.'
              type: boolean
              default: false
              example: true
            googleGoto:
              description: Ignored since 8th September 2026. Every redirect link now ships as `redirectLink` beside its destination, so both are returned without this flag. Requests still sending it behave as if it were absent.
              type: boolean
              default: false
              example: true
              deprecated: true
          default:
            html: false
          additionalProperties: false
      additionalProperties: false
    ChatGPTMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: ChatGPT's response data
          type: object
          properties:
            text:
              type: string
              description: ChatGPT's response text
              example: 'The name "Acme Corporation" is used in various contexts, both fictional and real. Here''s an overview:


                🐾 Acme Corporation in Fiction

                The Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.'
            sources:
              type: array
              description: Array of sources referenced in the response. Returns empty array when no sources are available.
              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://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com
                  label:
                    type: string
                    description: The article title of the source
                    example: 12 Best AI Recruiting Tools For HR in 2025
                  description:
                    type: string
                    description: A snippet or summary of the source content
                    example: Discover the top AI recruiting tools that can help HR professionals streamline their hiring process...
                  footnote:
                    type: boolean
                    description: Whether this source appears as a footnote (in a subsequent list in the sources modal)
                    example: false
                  datePublished:
                    type: string
                    description: The publication date of the source. Omitted from the response when the source has no publish date — never emitted as `null`.
                    example: May 22, 2025
              example:
              - 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
            html:
              type: string
              format: uri
              description: A URL to the full HTML of the response (included when include.html is true)
              example: https://cdn.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html
            markdown:
              type: string
              description: ChatGPT's response formatted in Markdown (included when include.markdown is true)
              example: 'The name "Acme Corporation" is used in various contexts, both fictional and real. Here''s an overview:


                🐾 Acme Corporation in Fiction

                The Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.'
            rawResponse:
              type: array
              description: Array of streaming events returned by ChatGPT (included when include.rawResponse is true). With `include.shopping` on as well, it includes the `product_update` events fetched for each inline product and shopping-card product.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Event type identifier
                  token:
                    type: string
                    description: Resume token used to continue the ChatGPT conversation
                  conversation_id:
                    type: string
                    description: ChatGPT conversation identifier
                  message:
                    type: object
                    description: Event payload describing the assistant message
                    properties:
                      id:
                        type: string
                      role:
                        type: string
                      model:
                        type: string
                  delta:
                    type: object
                    description: Streaming delta payload from ChatGPT
                    properties:
                      content:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                            text_delta:
                              type: string
                  reason:
                    type: string
                    description: Why ChatGPT stopped streaming
              example:
              - type: resume_conversation_token
                token: eyJhbGciOiJFUzI1Ni...WaVoqQ
                conversation_id: 68efc64b-2d74-8012-b87d-28e59f3b8a49
              - type: message_start
                message:
                  id: msg_01JD6Q7H1ZKWM9GD34V5ZW1TYM
                  role: assistant
                  model: gpt-5
              - type: message_delta
                delta:
                  content:
                  - type: output_text_delta
                    text_delta: The name "Acme Corporation" is used in various contexts...
              - type: message_stop
                reason: end_turn
            searchQueries:
              type: array
              description: Array of query fan-out ChatGPT used to generate the response (included when include.searchQueries is true)
              items:
                type: string
              example:
              - What is Acme Corporation?
              - Acme Corp company overview
              - Acme Corporation products and services
            mapSearchQueries:
              type: array
              description: Queries ChatGPT sent to its maps tool to build the `map` entries, deduplicated in first-seen order (included when include.searchQueries is true). Distinct from `searchQueries`, the web-search fan-out. Empty on responses served through OpenAI's mobile-web format; see `legacy`.
              items:
                type: string
              example:
              - coffee shops near Union Square San Francisco
            model:
              type: string
              nullable: true
              description: The ChatGPT model used to generate the response. Empty on responses served through OpenAI's mobile-web format.
              example: gpt-5-5
            shoppingCards:
              type: array
              description: Array of shopping/product cards extracted from the response. The field is omitted entirely from `result` when `include.shopping` is `false` or unset — clients should treat it as optional rather than expecting an empty array.
              items:
                type: object
                properties:
                  tags:
                    type: array
                    description: Category tags for the shopping card
                    items:
                      type: string
                    example:
                    - stylish casual leather sneaker
                    - heritage retro leather sneaker
                  products:
                    type: array
                    description: Array of product information
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: Product name
                          example: Adidas VL Court 3.0
                        position:
                          type: integer
                          description: 1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).
                          example: 1
                        url:
                          type: string
                          description: Product page URL with ChatGPT attribution
                          example: https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
                        price:
                          type: string
                          description: Current price
                          example: $57.00
                        featured_tag:
                          type: string
                          description: Product category or style tag
                          example: stylish casual leather sneaker
                        merchant:
                          type: string
                          description: Merchant information
                          example: adidas + others
                        image_urls:
                          type: array
                          description: Array of product image URLs
                          items:
                            type: string
                          example:
                          - https://images.openai.com/static-rsc-1/example.jpg
                        rating:
                          type: number
                          description: Product rating (0-5 scale)
                          example: 4.7
                        num_reviews:
                          type: integer
                          description: Number of reviews
                          example: 10394
                        id:
                          type: string
                          description: Unique product identifier
                          example: '3250714974047560249'
                        offers:
                          type: array
                          description: Array of shopping offers from different merchants
                          items:
                            type: object
                            properties:
                              merchant_name:
                                type: string
                                description: Merchant name
                                example: adidas
                              marketplace_seller:
                                type:
                                - string
                                - 'null'
                                description: Third-party seller on the marketplace
                              seller_name:
                                type: string
                                description: Seller name
                              brand:
                                type:
                                - string
                                - 'null'
                                description: Product brand. Set on only some offers, so often `null` or absent.
                              product_name:
                                type: string
                                description: Product name as listed by merchant
                                example: Adidas Women's VL Court 3.0
                              url:
                                type: string
                                description: Offer URL with ChatGPT attribution
                                example: https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
                              price:
                                type: string
                                description: Offer price
                                example: $57.00
                              details:
                                type: string
                                description: Stock and delivery information
                                example: In stock online and nearby, Delivery between Sat - Mon $4.99
                              available:
                                type: boolean
                                description: Offer availability status
                                example: true
                              checkoutable:
                                type: boolean
                                description: Whether offer can be checked out directly
                                example: false
                              price_details:
                                type: object
                                description: Detailed price breakdown
                                properties:
                                  base:
                                    type: string
                                    description: Base product price
                                    example: $57.00
                                  total:
                                    type: string
                                    description: Total price including any additional costs
                                    example: $57.00
                              tag:
                                type: object
                                description: Promotional tag
                                properties:
                                  text:
                                    type: string
                                    description: Tag text
                                    example: Best price
                        rating_grouped_citation:
                          type: object
                          description: Rating source information
                          properties:
                            title:
                              type: string
                              description: Source title
                              example: Adidas Women's VL Court 3.0
                            url:
                              type: string
                              description: Source URL
                              example: https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html
                            supporting_websites:
                              type: array
                              description: Array of supporting website references
                              items:
                                type: object
                                properties:
                                  title:
                                    type: string
                                    description: Website title
                                    example: Adidas Women's VL Court 3.0
                                  url:
                                    type: string
                                    description: Website URL
                                    example: https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla
              example:
              - tags:
                - stylish casual leather sneaker
                - heritage retro leather sneaker
                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/example.jpg
                  rating: 4.7
                  num_reviews: 10394
                  id: '3250714974047560249'
                  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
                  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
            inlineProducts:
              type: array
              description: Array of inline products with pricing and offers. The field is omitted entirely from `result` when `include.shopping` is `false` or unset — clients should treat it as optional rather than expecting an empty array.
              items:
                $ref: '#/components/schemas/InlineProduct'
            entities:
              type: array
              description: Array of entities extracted from the response (when available)
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Entity type identifier
                    example: product
                  name:
                    type: string
                    description: Entity name
                    example: adidas Grand Court Lo
                required:
                - type
                - name
              example:
              - type: product
                name: adidas Grand Court Lo
              - type: product
                name: Reebok Club C 85 Vintage
              - type: product
                name: Nike Dunk Low Retro SE
            map:
              type: array
              description: Array of business/place map entries extracted from the response (when available). Items come from ChatGPT's enriched providers (Yelp, Google Business) and use camelCase field names. The full field set is documented at /api-reference/endpoint/chatgpt/map; only the most commonly populated fields are listed here.
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Business ID (Yelp ID or Google Place ID)
                    example: rVKID2OBQMyVpraqSjz9sg
                  provider:
                    type: string
                    description: 'Data provider: "yelp", "b1"/"b3" (Google), or "yelp-feed"'
                    example: yelp
                  name:
                    type: string
                    description: Business name
                    example: Blue Bottle Coffee
                  position:
                    type: integer
                    description: Position/ranking in results (added by parser)
                    example: 1
                  address:
                    type: string
                    description: Full street address
                    example: 66 Mint St, San Francisco, CA 94103
                  latitude:
                    type: number
                    description: GPS latitude coordinate
                    example: 37.7811
                  longitude:
                    type: number
                    description: GPS longitude coordinate
                    example: -122.4076
                  categories:
                    type: array
                    description: Business categories
                    items:
                      type: string
                    example:
                    - Coffee shop
                  rating:
                    type: number
                    description: Business rating (0-5 scale)
                    example: 4.5
                  reviewCount:
                    type: integer
                    description: Number of reviews
                    example: 1234
                  description:
                    type: string
                    description: Business description
                    example: Specialty coffee roaster known for their meticulous pour-over preparations
                  phone:
                    type: string
                    description: Contact phone number
                    example: +1-415-555-0123
                  websiteUrl:
                    type: string
                    format: uri
                    description: Business website URL
                    example: https://bluebottlecoffee.com
              example:
              - id: rVKID2OBQMyVpraqSjz9sg
                provider: yelp
                name: Blue Bottle Coffee
                position: 1
                address: 66 Mint St, San Francisco, CA 94103
                latitude: 37.7811
                longitude: -122.4076
                categories:
                - Coffee shop
                rating: 4.5
                reviewCount: 1234
                description: Specialty coffee roaster known for their meticulous pour-over preparations
                phone: +1-415-555-0123
                websiteUrl: https://bluebottlecoffee.com
            citationPills:
              type: array
              description: Array of inline citation pills extracted from the response (when available). These are citations that appear inline within the text. Each entry is one (pill, source) pair; group by `citationPillId` to recover pill-level structure.
              items:
                type: object
                required:
                - label
                - citationPillId
                - url
                - domain
                - type
                - position
                properties:
                  url:
                    type: string
                    format: uri
                    description: The URL of the citation
                    example: https://example.com/article
                  label:
                    type: string
                    description: Per-source title of the citation. Always present; may be an empty string when the citation event ships no title — read `domain` / `url` for source identity in that case.
                    example: Example Article Title
                  description:
                    type: string
                    description: Description of the citation content. Omitted when the citation event carries no snippet (e.g. grouped-webpage title-only cards).
                    example: A detailed description of the cited content
                  domain:
                    type: string
                    description: Domain of the citation source
                    example: example.com
                  datePublished:
                    type: string
                    description: ISO 8601 date string of when the source was published. Omitted when the citation event carries no publication date.
                    example: '2025-01-01'
                  citationPillId:
                    type: integer
                    description: 0-based identifier shared by all entries from the same chip. Group by `citationPillId` to recover the pill-level structure. **Note:** unlike the other providers (Google AIO, AI Mode, Copilot, Perplexity, Gemini) which use 1-based `citationPillId`, ChatGPT's IDs start at 0 for historical reasons.
                    example: 0
                  type:
                    type: string
                    enum:
                    - searchResult
                    - groupedWebpage
                    description: 'Discriminator for the underlying citation event: `searchResult` for inline search citations, `groupedWebpage` for grouped-webpage cards.'
                    example: searchResult
                  position:
                    type: integer
                    description: 1-based position of this source in the sibling `result.sources` array.
                    example: 1
              example:
              - url: https://example.com/article
                label: Example Article Title
                description: A detailed description of the cited content
                domain: example.com
                datePublished: '2025-01-01'
                citationPillId: 0
                type: searchResult
                position: 1
            ads:
              type: array
              description: Array of ads served in the ChatGPT response (included when include.ads is true). OpenAI serves candidate ads but the interface renders at most one; use `rendered` to identify which were actually shown.
              items:
                type: object
                properties:
                  brand:
                    type: object
                    description: Advertiser brand information
                    properties:
                      name:
                        type: string
                        description: Advertiser brand name
                        example: Acme Shoes
                      url:
                        type: string
                        format: uri
                        description: Advertiser brand URL
                        example: https://www.acmeshoes.com?utm_source=chatgpt.com
                      favicon:
                        type: string
                        format: uri
                        description: Advertiser brand favicon URL
                        example: https://images.openai.com/favicon.ico
                    required:
                    - name
                    - url
                  cards:
                    type: array
                    description: Array of carousel cards in the ad
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: Card title
                          example: Premium Running Shoes
                        body:
                          type: string
                          description: Card description text
                          example: Lightweight performance running shoes with advanced cushioning technology
                        url:
                          type: string
                          format: uri
                          description: Card destination URL
                          example: https://www.acmeshoes.com/running?utm_source=chatgpt.com
                        image:
                          type: string
                          format: uri
                          description: Card image URL
                          example: https://images.openai.com/product.jpg
                      required:
                      - title
                      - body
                      - url
                  visibility:
                    type: string
                    description: OpenAI serving status for the ad. `allowed` means the ad was eligible to serve; `hidden` means OpenAI filtered it (for example, an integrity check).
                    example: allowed
                  adsResponseIndex:
                    type: integer
                    description: The ad's slot position in OpenAI's served ad response. This reflects served order, not what was shown — use `rendered` for actual exposure.
                    example: 0
                  rendered:
                    type: boolean
                    description: 'Whether the ad was shown as a visible card in the response. OpenAI serves several candidates but the interface renders at most one; ads with `rendered: false` were served but not displayed.'
                    example: true
                required:
                - brand
                - cards
                - visibility
                - adsResponseIndex
                - rendered
              example:
              - brand:
                  name: Acme Shoes
                  url: https://www.acmeshoes.com?utm_source=chatgpt.com
                  favicon: https://images.openai.com/favicon.ico
                cards:
                - title: Premium Running Shoes
                  body: Lightweight performance running shoes with advanced cushioning technology
                  url: https://www.acmeshoes.com/running?utm_source=chatgpt.com
                  image: https://images.openai.com/product.jpg
                - title: Trail Running Shoes
                  body: Durable shoes designed for off-road running with superior grip
                  url: https://www.acmeshoes.com/trail?utm_source=chatgpt.com
                  image: https://images.openai.com/product2.jpg
    CopilotMonitorRequest:
      required:
      - prompt
      - country
      type: object
      properties:
        prompt:
          description: The prompt to send to Copilot
          type: string
          minLength: 1
          maxLength: 10000
          example: What are the best laptops for programming?
        country:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        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
    AiModeMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: AI Mode response data
          type: object
          properties:
            text:
              type: string
              description: AI Mode's response text
              example: Here are some excellent laptop recommendations for programming...
            html:
              type: string
              format: uri
              description: A URL to the full HTML of the response.
              example: https://cdn.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: AI Source
                  description:
                    type: string
                    description: A description of the source content
                    example: AI-generated recommendations
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
              example:
              - position: 1
                url: https://example.com/ai-recommendations
                label: AI Source
                description: AI-curated laptop recommendations
            citationPills:
              type: array
              description: 'Inline citation pills extracted from the AI Mode answer. Each entry is one (pill, source) pair: when a pill cites N sources (Google''s `[Label +N]` chips), 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
                properties:
                  label:
                    type: string
                    description: Per-source title from the sources rail (for example `"Best Laptops 2026 — Reuters"`). Empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.
                    example: Best Laptops 2026 — Reuters
                  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://example.com/best-laptops-2026
                  domain:
                    type: string
                    description: Host extracted from `url`, for grouping and display.
                    example: example.com
                  description:
                    type: string
                    description: Source description from the sources rail when Google ships one. Omitted when the source carries no snippet.
                    example: A guide to the top laptops for software development this year.
                  position:
                    type: integer
                    description: 1-based position of this source in the sibling `result.sources` array. Omitted when the cited source isn't in `result.sources`.
                    example: 1
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
              example:
              - label: Best Laptops 2026 — Reuters
                citationPillId: 1
                url: https://example.com/best-laptops-2026
                domain: example.com
                description: A guide to the top laptops for software development this year.
                position: 1
              - label: MacBook Pro M4 Hands-On Review
                citationPillId: 1
                url: https://example.com/macbook-pro-review
                domain: example.com
                position: 3
            markdown:
              type: string
              description: AI Mode's response formatted in Markdown (included when include.markdown is true). Converted from Google's live page, so element order can shift as Google updates its markup.
              example: Here are some excellent laptop recommendations for programming...
            places:
              type: array
              description: Inline place cards extracted from the response
              items:
                $ref: '#/components/schemas/GooglePlace'
            shoppingCards:
              type: array
              description: Shopping product information extracted from the response
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Product title
                    example: Wireless Headphones
                  price:
                    type: object
                    description: Price as displayed. `raw` is always present; `value` and `currency` are omitted when they can't be parsed, never sent as `null`.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 99.99
                      currency:
                        type: string
                        description: Currency symbol or word as displayed (e.g. `$`, `R$`)
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $99.99
                  store:
                    type: string
                    description: Merchant/store name
                    example: Amazon
                  rating:
                    type: number
                    description: Product rating
                    example: 4.2
                  reviews:
                    type: string
                    description: Review count
                    example: 2.3k
                  thumbnail:
                    type: string
                    format: uri
                    description: Product image
                    example: https://example.com/product.jpg
                  productLink:
                    type: string
                    format: uri
                    description: Direct product URL
                    example: https://www.google.com/example
                  oldPrice:
                    type: object
                    description: Original price before discount. Same shape as `price`.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 129.99
                      currency:
                        type: string
                        description: Currency symbol or word as displayed (e.g. `$`, `R$`)
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $129.99
                  snippet:
                    type: string
                    description: Product description snippet
                    example: Noise-canceling wireless headphones with 30-hour battery life
                  snippetLinks:
                    type: array
                    description: Links found within the product snippet
                    items:
                      type: object
                      properties:
                        text:
                          type: string
                          description: Link text
                          example: noise canceling
                        link:
                          type: string
                          format: uri
                          description: Link URL
                          example: https://www.google.com/search?q=noise+canceling
                        redirectLink:
                          type: string
                          description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                          example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                  position:
                    type: integer
                    description: 1-indexed rank across the `shoppingCards` array in DOM/render order.
                    example: 1
            ads:
              type: object
              description: Sponsored ad section extracted from the response
              properties:
                title:
                  type: string
                  description: Section title for the ads
                  example: Here are some 3D printers to consider
                ads:
                  type: array
                  description: Array of sponsored ads
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Ad product title
                        example: Bambu Lab X2D
                      url:
                        type: string
                        format: uri
                        description: Ad click-through URL
                        example: https://www.google.com/aclk?sa=L&ai=abc
                      position:
                        type: integer
                        description: Position index of the ad
                        example: 1
                      price:
                        type: object
                        description: Price as displayed. `raw` is always present; `value` and `currency` are omitted when they can't be parsed, never sent as `null`.
                        properties:
                          value:
                            type: number
                            description: Numeric price
                            example: 899.0
                          currency:
                            type: string
                            description: Currency symbol or word as displayed (e.g. `$`, `R$`)
                            example: $
                          raw:
                            type: string
                            description: Visible price text verbatim
                            example: $899.00
                      store:
                        type: string
                        description: Merchant/store name
                        example: Bambu Lab US
                      rating:
                        type: number
                        description: Product rating
                        example: 4.7
                      reviews:
                        type: string
                        description: Review count
                        example: '584'
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            inlineProducts:
              type: array
              description: Inline product cards found within the AI response text
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: Product title
                    example: Sony WH-1000XM5
                  position:
                    type: integer
                    description: 1-indexed rank across the `inlineProducts` array in DOM/render order.
                    example: 1
                  price:
                    type: object
                    description: Price as displayed. Fields that can't be parsed are omitted, never sent as `null`. When Google supplies structured price data, `currency` is an ISO code (`USD`) and `raw` appears only if the page also showed the price text.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 298.0
                      currency:
                        type: string
                        description: Currency symbol as displayed, or an ISO code when Google supplies structured price data
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $298.00
                  oldPrice:
                    type: object
                    description: Original price before discount. Same shape as `price`.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 399.99
                      currency:
                        type: string
                        description: Currency symbol as displayed, or an ISO code when Google supplies structured price data
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $399.99
                  store:
                    type: string
                    description: Merchant/store name
                    example: Amazon
                  thumbnail:
                    type: string
                    format: uri
                    description: Product image URL
                    example: https://encrypted-tbn0.gstatic.com/images?q=example
                  productLink:
                    type: string
                    format: uri
                    description: Direct product URL
                    example: https://www.google.com/shopping/product/example
            videos:
              type: array
              description: Inline video cards embedded in the AI response (currently YouTube)
              items:
                type: object
                required:
                - title
                - link
                properties:
                  title:
                    type: string
                    description: Video title
                    example: The BEST 3D Printer for YOU - Don't Buy the Wrong One!
                  link:
                    type: string
                    format: uri
                    description: Canonical watch URL (timestamp parameters stripped)
                    example: https://www.youtube.com/watch?v=g0DZnQdI-xQ
                  platform:
                    type: string
                    description: Hosting platform parsed from the card byline
                    example: YouTube
                  channel:
                    type: string
                    description: Channel or uploader name
                    example: 3D Print Dood
                  duration:
                    type: string
                    description: Visible duration label (mm:ss or hh:mm:ss)
                    example: 08:49
                  thumbnail:
                    type: string
                    format: uri
                    description: Public thumbnail URL
                    example: https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            map:
              type: array
              description: GPS-enriched location data extracted from the response
              items:
                $ref: '#/components/schemas/GoogleMapPlace'
            productResults:
              type: array
              description: Merchant offers per product cluster, up to 6. Returned only when `include.expandProducts` is true. See [product results](/api-reference/endpoint/aimode/product-results).
              items:
                $ref: '#/components/schemas/ProductResult'
    InternalError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_SERVER_ERROR
            message:
              type: string
              description: For example `Maximum retries exceeded` when every attempt failed, or `Internal server error` for an unexpected failure.
              example: Maximum retries exceeded
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    GoogleMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Google search results data
          type: object
          properties:
            organicResults:
              type: array
              description: Organic search results from Google
              items:
                type: object
                properties:
                  position:
                    type: number
                    description: Position in search results (1-indexed)
                    example: 1
                  title:
                    type: string
                    description: Title of the search result
                    example: Best Laptops for Programming in 2024
                  link:
                    type: string
                    description: URL of the search result
                    example: https://example.com/best-programming-laptops
                  displayedLink:
                    type: string
                    description: Formatted URL as displayed in search results
                    example: https://example.com
                  snippet:
                    type: string
                    description: Text snippet describing the page content
                    example: Looking for the best programming laptops? We've tested and reviewed the top options...
                  date:
                    type: string
                    description: Publication date if available
                    example: 2 days ago
                  page:
                    type: number
                    description: Page number this result appeared on (1-indexed)
                    example: 1
                  sitelinks:
                    type: object
                    description: Sitelinks displayed under the main result
                    properties:
                      inline:
                        type: array
                        description: Inline sitelinks
                        items:
                          type: object
                          properties:
                            title:
                              type: string
                              example: Specifications
                            link:
                              type: string
                              example: https://example.com/specs
                            redirectLink:
                              type: string
                              description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                              example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            peopleAlsoAsk:
              type: array
              description: People Also Ask questions from Google
              items:
                type: object
                properties:
                  question:
                    type: string
                    description: The question text
                    example: What specs should I look for in a programming laptop?
                  type:
                    type: string
                    enum:
                    - AIOVERVIEW
                    - LINK
                    - UNKNOWN
                    description: Type of question result
                  snippet:
                    type: string
                    description: Answer snippet (for LINK type)
                    example: Key specifications include RAM, processor, storage, and display quality...
                  title:
                    type: string
                    description: Result title (for LINK type)
                    example: Essential laptop specs for developers
                  link:
                    type: string
                    description: Result URL (for LINK type)
                    example: https://example.com/laptop-specs
                  markdown:
                    type: string
                    description: AI Overview markdown content (for AIOVERVIEW type, when include.paaAioverview is true)
                  sources:
                    type: array
                    description: Cited sources (for AIOVERVIEW type, when include.paaAioverview is true)
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          description: Title of the source
                          example: Programming Laptop Guide
                        url:
                          type: string
                          description: URL of the source
                          example: https://example.com/guide
                        description:
                          type: string
                          description: Description of the source
                        position:
                          type: number
                          description: Position of source (1-indexed)
                        redirectLink:
                          type: string
                          description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                          example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            peopleAreSaying:
              type: array
              description: Cards from Google's "What people are saying" / "Trending posts and discussions" SERP module. The field is omitted from `result` when no such module appears on the SERP, so clients should treat it as optional rather than expecting an empty array.
              items:
                type: object
                required:
                - position
                - title
                - link
                - date
                properties:
                  position:
                    type: number
                    description: Position within the module (1-indexed)
                    example: 1
                  title:
                    type: string
                    description: Card title as displayed on the SERP
                    example: Best running shoes 2026 - what runners are saying
                  link:
                    type: string
                    description: Destination URL the card points to (often a Reddit, Quora, or community forum thread)
                    example: https://www.reddit.com/r/running/comments/example/
                  date:
                    type: string
                    description: Google's raw relative-time text (e.g., "5 days ago", "2 weeks ago"). Free-form string — not normalized to a timestamp.
                    example: 5 days ago
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            localResults:
              type: array
              description: Places from Google's local pack (the map-backed "3-pack" of local businesses on local-intent queries, e.g. "best pizza in new york city"). The field is omitted from `result` when no local pack appears on the SERP, so clients should treat it as optional rather than expecting an empty array. Desktop only; mobile and the separate hotels/travel pack are not surfaced.
              items:
                type: object
                required:
                - position
                - title
                properties:
                  position:
                    type: number
                    description: Position within the pack (1-indexed)
                    example: 1
                  title:
                    type: string
                    description: Business name as displayed on the SERP
                    example: Joe's Pizza Broadway
                  placeId:
                    type: string
                    description: Google entity id for the place
                    example: /g/11bw4ws2mt
                  rating:
                    type: number
                    description: Average star rating (0–5)
                    example: 4.4
                  reviews:
                    type: string
                    description: Review count as displayed by Google (e.g. "26K"). Free-form string — not normalized to a number.
                    example: 26K
                  price:
                    type: string
                    description: Price band as displayed by Google (e.g. "$10–20"). Currency symbol matches the locale.
                    example: $10–20
                  type:
                    type: string
                    description: Business category (e.g. "Pizza", "Plumber")
                    example: Pizza
                  yearsInBusiness:
                    type: string
                    description: Years-in-business badge, when shown (typical on service-style packs)
                    example: 80+ years in business
                  address:
                    type: string
                    description: Street address or locality as displayed on the SERP
                    example: 1435 Broadway
                  phone:
                    type: string
                    description: Phone number, when shown (locale-formatted)
                    example: (212) 555-0100
                  hours:
                    type: string
                    description: Opening-hours text as displayed (e.g. "Open · Closes 11 PM", "Open 24 hours")
                    example: Open · Closes 11 PM
                  description:
                    type: string
                    description: Trailing snippet — a review quote or a service-options line
                    example: '"Fast service, great atmosphere, and truly scrumptious pizza."'
                  links:
                    type: object
                    description: Action links rendered on the place, typically on business/service-style packs (plumbers, salons, …) and absent on restaurant packs whose places are plain buttons. Each key is present only when Google rendered that button.
                    properties:
                      website:
                        type: string
                        description: The business's own website URL
                        example: https://villageplumbing.com/
                      directions:
                        type: string
                        description: Absolute Google Maps directions URL
                        example: https://www.google.com/maps/dir//Village+Plumbing,+Air+%26+Electric
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            localResultsMoreLink:
              type: string
              description: Absolute URL of the local pack's "More places" / "More businesses" control — Google's expanded Local Finder for the query. Returned only alongside `localResults` when the SERP renders the control.
              example: https://www.google.com/search?q=italian+restaurants+in+toronto&udm=1
            relatedSearches:
              type: array
              description: Related search suggestions
              items:
                type: object
                properties:
                  query:
                    type: string
                    description: Related search query
                    example: best budget laptop for coding
                  link:
                    type: string
                    description: Google search URL for the related query
                    example: https://google.com/search?q=best+budget+laptop+for+coding
            ads:
              type: array
              description: 'Sponsored ad results from Google search, including text ads (`type: RESULT`) and shopping-style sponsored cards (`type: SHOPPING_CARD`) from the right-hand-side and top-of-page carousels.'
              items:
                type: object
                properties:
                  position:
                    type: number
                    description: Position within the ad block (1-indexed)
                    example: 1
                  blockPosition:
                    type: string
                    enum:
                    - top
                    - bottom
                    - middle
                    - rhs
                    description: Where the ad appeared on the SERP. `top`/`bottom` are text-ad blocks, `middle` covers direct/in-content ads, `rhs` is the right-hand-side sponsored-products carousel.
                    example: top
                  type:
                    type: string
                    enum:
                    - RESULT
                    - SHOPPING_CARD
                    description: Discriminates plain text ads (`RESULT`) from shopping-style sponsored cards (`SHOPPING_CARD`). Shopping cards appear in the right-hand-side PLA carousel, the top-of-page PLA carousel, and the top-of-page sponsored shopping-card carousels (vehicles, products, hotels, …).
                    example: RESULT
                  title:
                    type: string
                    description: Ad title
                    example: Best Programming Laptops - Shop Now
                  url:
                    type: string
                    format: uri
                    description: 'Destination URL of the ad. For `type: SHOPPING_CARD` items this is a Google `aclk?`-redirected URL.'
                    example: https://example.com/programming-laptops
                  page:
                    type: number
                    description: Page number where the ad was found
                    example: 1
                  displayedUrl:
                    type: string
                    description: Formatted URL as displayed in the ad
                    example: example.com/laptops
                  domain:
                    type: string
                    description: Domain name of the advertiser
                    example: example.com
                  description:
                    type: string
                    description: 'Ad description text. For `type: RESULT` items this is classic ad copy. For `type: SHOPPING_CARD` items it carries category-specific subtitle fragments joined with `·` (e.g. vehicle condition + city: `Used - 94k miles · Greeley`).'
                    example: Shop our selection of programming laptops with fast shipping.
                  category:
                    type: string
                    description: 'Carousel header label for shopping-card ads. Examples observed today include `Sponsored products`, `Sponsored vehicles`, and `Sponsored hotels`. Omitted for `type: RESULT` text ads.'
                    example: Sponsored products
                  price:
                    type: object
                    description: 'Product price for `type: SHOPPING_CARD` ads. `currency` and `raw` are always present; `value` is omitted when the number doesn''t parse, and the whole object is omitted when no currency appears beside a number. `raw` carries the visible text verbatim (e.g. `"$0 down with 24 monthly payments"` on installment offers) so consumers can disambiguate genuine zero prices from down-payment labels.'
                    properties:
                      value:
                        type: number
                        description: Numeric price value
                        example: 1199
                      currency:
                        type: string
                        description: Currency symbol
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $1,199
                  oldPrice:
                    type: object
                    description: 'Original price before discount on `type: SHOPPING_CARD` ads that surface MSRP / sale messaging. Same shape as `price`.'
                    properties:
                      value:
                        type: number
                        description: Numeric price value
                        example: 1299
                      currency:
                        type: string
                        description: Currency symbol
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $1,299
                  store:
                    type: string
                    description: 'Merchant/dealer name attached to a `type: SHOPPING_CARD` ad.'
                    example: Apple
                  imageUrl:
                    type: string
                    format: uri
                    description: 'Hero image URL served by Google''s `encrypted-tbn` CDN for `type: SHOPPING_CARD` ads. Omitted when the lazy-image chain cannot resolve a non-placeholder source.'
                    example: https://encrypted-tbn0.gstatic.com/images?q=tbn:...
                  sitelinks:
                    type: array
                    description: Sitelinks displayed under the ad
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: Sitelink URL
                          example: https://example.com/gaming-laptops
                        title:
                          type: string
                          description: Sitelink title
                          example: Gaming Laptops
                        description:
                          type: string
                          description: Sitelink description
                          example: High-performance laptops for gaming
            aioverview:
              oneOf:
              - type: object
              - type: 'null'
              description: Google AI Overview data (if requested). Omitted when Google shows no AI Overview for the query.
              properties:
                sources:
                  type: array
                  description: Sources referenced in the AI Overview
                  items:
                    type: object
                    properties:
                      position:
                        type: number
                        description: 1-based position index of the source
                        example: 1
                      url:
                        type: string
                        description: Source URL
                        example: https://example.com/programming-laptops
                      label:
                        type: string
                        description: Source title (the display label Google renders on the source rail)
                        example: Best Programming Laptops 2026
                      description:
                        type: string
                        description: Source description / snippet
                        example: Comprehensive guide to choosing the perfect laptop for software development
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                citationPills:
                  type: array
                  description: 'Inline citation pills extracted from the AI Overview answer. Each entry is one (pill, source) pair: when a pill cites N sources (Google''s `[Label +N]` chips), 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.aioverview` 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 (for example `"Chase Personal Credit Cards"`). Empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case. Entries grouped under the same `citationPillId` carry different per-source labels.
                        example: Chase Personal Credit Cards
                      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://www.chase.com/personal/credit-cards
                      domain:
                        type: string
                        description: Host extracted from `url`, for grouping and display.
                        example: chase.com
                      description:
                        type: string
                        description: Source description from the sources rail when Google ships one. Omitted when the source carries no snippet.
                        example: Personal credit cards from Chase.
                      position:
                        type: integer
                        description: 1-based position of this source in the sibling `result.aioverview.sources` array.
                        example: 2
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                  example:
                  - label: Chase Personal Credit Cards
                    citationPillId: 1
                    url: https://www.chase.com/personal/credit-cards
                    domain: chase.com
                    description: Personal credit cards from Chase.
                    position: 2
                  - label: JustAnswer Computer Help
                    citationPillId: 1
                    url: https://www.justanswer.com/computer/help
                    domain: justanswer.com
                    position: 4
                relatedLinks:
                  type: array
                  description: A citation chip's "View related links" flyout items — URLs Google groups under the chip that are NOT in the `sources` rail (for example a Google Shopping comparison link). Each entry shares the `citationPillId` of its chip so it can be grouped with that chip's `citationPills`, but carries no `position` (a related link is absent from `sources`). Related links also render inline in `markdown`, so `markdown` may contain more URLs than `sources` / `citationPills` — the extras are accounted for here. Omitted from `result.aioverview` when no chip carries related links.
                  items:
                    type: object
                    required:
                    - label
                    - citationPillId
                    - url
                    - domain
                    properties:
                      label:
                        type: string
                        description: The related page's own title. Empty string when Google ships none — read `domain` / `url` for identity in that case.
                        example: Compare developer laptops
                      citationPillId:
                        type: integer
                        description: Matches the `citationPillId` of the chip's `citationPills` entries, so a related link can be grouped with its pill.
                        example: 1
                      url:
                        type: string
                        description: Direct URL of the related link.
                        example: https://www.google.com/search?q=developer+laptops&ibp=oshop
                      domain:
                        type: string
                        description: Host extracted from `url`, for grouping and display.
                        example: google.com
                      description:
                        type: string
                        description: Snippet Google ships for the related link. Omitted when absent.
                        example: Shop and compare laptops for developers.
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                  example:
                  - label: Compare developer laptops
                    citationPillId: 1
                    url: https://www.google.com/search?q=developer+laptops&ibp=oshop
                    domain: google.com
                text:
                  type: string
                  description: AI Overview text content
                  example: Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series...
                markdown:
                  type: string
                  description: AI Overview content formatted as markdown (if requested)
                  example: Based on current information, the best laptops for programming typically include models from Apple MacBook Pro, Dell XPS, and Lenovo ThinkPad series...
                videos:
                  type: array
                  description: Video content included in the AI Overview
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                        description: Direct URL to the video
                        example: https://www.youtube.com/watch?v=example
                      title:
                        type: string
                        description: Video title
                        example: Best Laptops for Programming 2024
                      thumbnail:
                        type: string
                        format: uri
                        description: Thumbnail image URL
                        example: https://example.com/thumbnail.jpg
                      source:
                        type: string
                        description: Channel or source name
                        example: Tech Channel
                      platform:
                        type: string
                        description: Video platform
                        example: YouTube
                      date:
                        type: string
                        description: Upload date
                        example: 2 days ago
                      duration:
                        type: string
                        description: Video duration
                        example: '12:34'
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                places:
                  type: array
                  description: Place cards in the AI Overview answer. Omitted when the answer has none.
                  items:
                    $ref: '#/components/schemas/GooglePlace'
                map:
                  type: array
                  description: The place cards that Google geo-tagged, with coordinates. Omitted when the answer has none.
                  items:
                    $ref: '#/components/schemas/GoogleMapPlace'
                ads:
                  type: array
                  description: Sponsored ads injected by Google inside the AI Overview
                  items:
                    type: object
                    required:
                    - position
                    - title
                    - url
                    - type
                    properties:
                      position:
                        type: number
                        description: Position of the ad (1-indexed)
                        example: 1
                      title:
                        type: string
                        description: Ad title
                        example: QA Software Testing Services - On-Demand Software Testing
                      url:
                        type: string
                        description: Ad destination URL
                        example: https://www.testlio.com
                      type:
                        type: string
                        enum:
                        - TEXT
                        - SHOPPING
                        description: Sub-type discriminator. TEXT ads carry `domain` + `description`; SHOPPING ads carry `price` + `store` (+ optional `old_price`). Always present.
                        example: TEXT
                      domain:
                        type: string
                        description: Domain name of the advertiser (present when `type` is `TEXT`)
                        example: Testlio
                      description:
                        type: string
                        description: Ad description text (present when `type` is `TEXT`)
                        example: Dynamic staffing. Global coverage. Managed manual testing and test automation solutions.
                      price:
                        type: object
                        description: Product price (present when `type` is `SHOPPING`). `currency` and `raw` are always present; `value` is omitted when the number doesn't parse, and the whole object is omitted when no currency appears beside a number. `raw` carries the visible text verbatim.
                        properties:
                          value:
                            type: number
                            description: Numeric price value
                            example: 69.99
                          currency:
                            type: string
                            description: Currency symbol
                            example: $
                          raw:
                            type: string
                            description: Visible price text verbatim
                            example: $69.99
                      old_price:
                        type: object
                        description: Original price before discount (present when `type` is `SHOPPING` and the ad has sale pricing). Same shape as `price`.
                        properties:
                          value:
                            type: number
                            description: Numeric price value
                            example: 99.99
                          currency:
                            type: string
                            description: Currency symbol
                            example: $
                          raw:
                            type: string
                            description: Visible price text verbatim
                            example: $99.99
                      store:
                        type: string
                        description: Retailer name (present when `type` is `SHOPPING`)
                        example: Best Buy
                      image:
                        type: string
                        description: Ad image URL (product photo for shopping ads, hero image for text ads)
                        example: https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ...
            shoppingCards:
              type: array
              description: 'Shopping product cards extracted from the SERP''s organic shopping grids ("Popular products" / "More products"). The field is omitted from `result` when no shopping section is present, so clients should treat it as optional rather than expecting an empty array. Cards carry no product URL: they open a Google-side overlay rather than an external page.'
              items:
                type: object
                required:
                - title
                - position
                properties:
                  title:
                    type: string
                    description: Product title
                    example: ASICS Women's Gel-Nimbus 28
                  position:
                    type: integer
                    description: 1-indexed rank across the whole `shoppingCards` array in DOM order (flat, does not reset per `category` section).
                    example: 1
                  promoLabel:
                    type: string
                    description: Discount badge as displayed by Google, in the SERP language (for example "LOW PRICE", "OFERTA", "PROMOÇÃO", "20% OFF"). Google renders it above the product name on a discounted card. Present only on a card that carries the badge, and Google-only — AI Mode does not render it.
                    example: 20% OFF
                  category:
                    type: string
                    description: Parent section header text. Lets callers distinguish cards from coexisting shopping panels on the same SERP. Current Google-emitted values include "Popular products" and "More products".
                    example: More products
                  price:
                    type: object
                    description: Structured pricing information. `currency` and `raw` are always present; `value` is omitted when the number doesn't parse, and the whole object is omitted when no currency appears beside a number. `raw` carries the visible text verbatim.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 169.99
                      currency:
                        type: string
                        description: Currency symbol
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $169.99
                  oldPrice:
                    type: object
                    description: Original price before discount. Same shape as `price`.
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 199.99
                      currency:
                        type: string
                        description: Currency symbol
                        example: $
                      raw:
                        type: string
                        description: Visible price text verbatim
                        example: $199.99
                  store:
                    type: string
                    description: Merchant/store name
                    example: DICK'S Sporting Goods
                  rating:
                    type: number
                    description: Product rating
                    example: 4.5
                  reviews:
                    type: string
                    description: Review count
                    example: '384'
                  thumbnail:
                    type: string
                    format: uri
                    description: Product image URL
                    example: https://example.com/product.jpg
            knowledgeGraph:
              description: Google's Knowledge Graph panel for the queried entity. Omitted from `result` when no Knowledge Graph panel appears on the SERP — treat it as optional rather than expecting null.
              type: object
              properties:
                title:
                  type: string
                  description: Entity name as shown in the panel header
                  example: Eminem
                type:
                  type: string
                  description: Entity category label as rendered by Google (e.g. "American rapper", "French museum"). Free-form string, not an enum.
                  example: American rapper
                kgmid:
                  type: string
                  description: Google Knowledge Graph ID for the entity
                  example: /m/01vs_v8
                description:
                  type: string
                  description: Short description of the entity (may be sourced from Wikipedia or Google's own knowledge base)
                  example: Marshall Bruce Mathers III, known professionally as Eminem, is an American rapper, songwriter, and record producer.
                imageUrl:
                  type: string
                  description: URL of the entity's image as served by Google
                  example: https://encrypted-tbn0.gstatic.com/images?q=tbn:...
                website:
                  type: string
                  description: Official website URL for the entity
                  example: https://www.eminem.com
                menu:
                  type: string
                  description: Menu URL — present for restaurants and food businesses
                  example: https://www.restaurant.com/menu
                trailer:
                  type: string
                  description: Trailer URL — present for films and TV shows
                  example: https://www.youtube.com/watch?v=example
                source:
                  type: object
                  description: Attribution source for the entity description (typically Wikipedia)
                  properties:
                    name:
                      type: string
                      description: Display name of the source
                      example: Wikipedia
                    link:
                      type: string
                      description: URL of the source page
                      example: https://en.wikipedia.org/wiki/Eminem
                    redirectLink:
                      type: string
                      description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                      example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                attributes:
                  type: array
                  description: Factual key-value pairs extracted from the panel (e.g. born, genre, label). Keys are free-form strings as rendered by Google.
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Attribute label
                        example: Born
                      value:
                        type: string
                        description: Attribute value
                        example: October 17, 1972
                profiles:
                  type: array
                  description: Social media and external profile links for the entity
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Platform or profile name
                        example: Instagram
                      link:
                        type: string
                        description: Profile URL
                        example: https://www.instagram.com/eminem/
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                peopleAlsoSearchFor:
                  type: array
                  description: Related entities that users also search for
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Related entity name
                        example: Jay-Z
                      link:
                        type: string
                        description: Google search URL for this related entity
                        example: https://www.google.com/search?q=Jay-Z
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                thingsToKnow:
                  type: array
                  description: '"Things to know" topic clusters extracted from the panel'
                  items:
                    type: object
                    properties:
                      label:
                        type: string
                        description: Topic cluster label
                        example: Albums
                      subtitle:
                        type: string
                        description: Subtitle or supporting text for the topic
                        example: The Slim Shady LP, The Marshall Mathers LP, ...
                ratings:
                  type: array
                  description: Review platform ratings (e.g. Rotten Tomatoes, IMDb) — present for films and TV shows
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Review platform name
                        example: Rotten Tomatoes
                      rating:
                        type: string
                        description: Rating value as displayed
                        example: 88%
                      link:
                        type: string
                        description: URL to the review page
                        example: https://www.rottentomatoes.com/m/8_mile
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                streamingOptions:
                  type: array
                  description: Streaming platform links for films and TV shows
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Streaming platform name
                        example: Netflix
                      link:
                        type: string
                        description: Link to the content on the platform
                        example: https://www.netflix.com/title/example
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                webRatings:
                  type: array
                  description: Web ratings from review platforms — present for local businesses (e.g. Google, Tripadvisor, Yelp)
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Rating platform name
                        example: Google
                      rating:
                        type: string
                        description: Rating value as displayed
                        example: '4.5'
                      link:
                        type: string
                        description: URL to the platform's review page
                        example: https://www.google.com/maps/place/...
                      votes:
                        type: string
                        description: Number of votes or reviews (omitted when not available)
                        example: 1,234
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                statsCard:
                  type: object
                  description: Statistics card — present for sports teams, organizations, and similar entities
                  properties:
                    context:
                      type: string
                      description: Context label for the stats (e.g. season or year)
                      example: 2023-24 NBA season
                    stats:
                      type: array
                      description: Individual stat items
                      items:
                        type: object
                        properties:
                          label:
                            type: string
                            description: Stat label
                            example: Points per game
                          value:
                            type: string
                            description: Stat value
                            example: '27.1'
                socialPosts:
                  type: array
                  description: Recent social media posts from the entity's official accounts
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Social platform name
                        example: X
                      text:
                        type: string
                        description: Post text content
                        example: New album dropping Friday 🔥
                      link:
                        type: string
                        description: URL to the post
                        example: https://x.com/eminem/status/...
                      date:
                        type: string
                        description: Post date as displayed by Google
                        example: 2 days ago
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                notableAlumni:
                  type: array
                  description: Notable alumni — present for universities and educational institutions
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Alumni name
                        example: Barack Obama
                      link:
                        type: string
                        description: Google search URL for this person
                        example: https://www.google.com/search?q=Barack+Obama
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                contact:
                  type: array
                  description: Contact and ordering links — present for local businesses
                  items:
                    type: object
                    properties:
                      label:
                        type: string
                        description: Link label
                        example: Order online
                      url:
                        type: string
                        description: Link URL
                        example: https://www.restaurant.com/order
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                weather:
                  type: object
                  description: Current weather — present for geographic entities (cities, regions)
                  properties:
                    temperature:
                      type: string
                      description: Temperature as displayed
                      example: 72°F
                    condition:
                      type: string
                      description: Weather condition
                      example: Sunny
                rating:
                  type: object
                  description: Aggregate star rating — present for local businesses
                  properties:
                    rating:
                      type: string
                      description: Star rating value
                      example: '4.5'
                    count:
                      type: string
                      description: Number of reviews
                      example: 2,847
                admission:
                  type: array
                  description: Admission options — present for museums, parks, and ticketed venues
                  items:
                    type: object
                    properties:
                      provider:
                        type: string
                        description: Ticket provider name
                        example: Official website
                      price:
                        type: string
                        description: Admission price as displayed
                        example: $17
                      link:
                        type: string
                        description: URL to purchase tickets
                        example: https://www.louvre.fr/en/tickets
                      badge:
                        type: string
                        description: Optional badge text (e.g. "Free", "Best price") — omitted when not present
                        example: Best price
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                artworks:
                  type: array
                  description: Notable artworks — present for artists and art institutions
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Artwork title
                        example: Mona Lisa
                      link:
                        type: string
                        description: Link to more information about the artwork
                        example: https://www.google.com/search?q=Mona+Lisa
                      author:
                        type: string
                        description: Author or creator name — omitted when not present
                        example: Leonardo da Vinci
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                has3dModel:
                  type: boolean
                  description: True when Google surfaces a 3D model viewer for the entity
                  example: true
                hotelOptions:
                  type: array
                  description: Hotel booking options — present for hotel entities
                  items:
                    type: object
                    properties:
                      provider:
                        type: string
                        description: Booking provider name
                        example: Booking.com
                      price:
                        type: string
                        description: Price as displayed
                        example: $189/night
                      link:
                        type: string
                        description: URL to book on this provider
                        example: https://www.booking.com/hotel/...
                      note:
                        type: string
                        description: Optional note (e.g. "Includes breakfast") — omitted when not present
                        example: Includes breakfast
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                trendingProducts:
                  type: array
                  description: Trending products — present for retail brands
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Product title
                        example: Air Max 90
                      price:
                        type: string
                        description: Price as displayed
                        example: $120
                      link:
                        type: string
                        description: Link to the product
                        example: https://www.nike.com/t/air-max-90
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                merchantVideos:
                  type: array
                  description: Merchant or brand video content — present for retail businesses
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Video title
                        example: Foot Locker Week of Greatness
                      link:
                        type: string
                        description: Video URL
                        example: https://www.youtube.com/watch?v=...
                      platform:
                        type: string
                        description: Video platform — omitted when not available
                        example: YouTube
                      duration:
                        type: string
                        description: Video duration as displayed — omitted when not available
                        example: '2:34'
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                listenOn:
                  type: array
                  description: Music streaming platform links — present for musicians and musical acts
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Streaming platform name
                        example: Spotify
                      link:
                        type: string
                        description: Link to the artist on the platform
                        example: https://open.spotify.com/artist/...
                      redirectLink:
                        type: string
                        description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                        example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
                redirectLink:
                  type: string
                  description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                  example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            productResults:
              type: array
              description: Merchant offers from the right-rail product panel. At most one entry, present only when Google shows the panel; no request flag needed. See [product results](/api-reference/endpoint/google/product-results).
              items:
                $ref: '#/components/schemas/ProductResult'
            html:
              type: array
              description: Raw HTML from Google search page (if requested)
              items:
                type: string
                format: uri
              example:
              - https://cdn.cloro.dev/results/b83e8dfd-c3a1-4b98-83b9-af91adc21e26/page-1.html
    ShowcaseMetadata:
      type: object
      description: Visual showcase metadata attached to a shopping product (image, background, and per-slot placement).
      properties:
        image:
          $ref: '#/components/schemas/ShowcaseImage'
        background:
          $ref: '#/components/schemas/ShowcaseBackground'
        slots:
          type: object
          description: Slot map keyed by slot identifier
          additionalProperties:
            $ref: '#/components/schemas/ShowcaseSlot'
        debug:
          type: object
          description: Free-form debug metadata; opaque to clients
          additionalProperties: true
    StateParameter:
      description: 'State code for sub-country geo-targeting (e.g., "CA"). Only valid with country "US". Paid add-on: +2 credits, on top of the base cost and any other add-on ([pricing](/guides/providers#state-level-targeting)).'
      type: string
      enum:
      - AL
      - AK
      - AZ
      - AR
      - CA
      - CO
      - CT
      - DE
      - DC
      - FL
      - GA
      - HI
      - ID
      - IL
      - IN
      - IA
      - KS
      - KY
      - LA
      - ME
      - MD
      - MA
      - MI
      - MN
      - MS
      - MO
      - MT
      - NE
      - NV
      - NH
      - NJ
      - NM
      - NY
      - NC
      - ND
      - OH
      - OK
      - OR
      - PA
      - RI
      - SC
      - SD
      - TN
      - TX
      - UT
      - VT
      - VA
      - WA
      - WV
      - WI
      - WY
      example: CA
      minLength: 2
      maxLength: 2
      pattern: ^[A-Z]{2}$
    GooglePlace:
      description: Place card from a Google AI answer
      allOf:
      - $ref: '#/components/schemas/GooglePlaceBase'
      - type: object
        properties:
          link:
            type: string
            format: uri
            description: Google viewer URL for the place. It is the URL of the place's entry in `sources`. Omitted when `sources` has no entry for the place.
            example: https://www.google.com/searchviewer/10?svid=CAwSGxIZCgNwdnESEkNnc3ZaeTh4ZGpGMGJqWTBlURgK
          priceLevel:
            type: string
            description: Price level indicator
            example: $$
    ShoppingOffer:
      type: object
      description: Shopping offer with pricing details from a specific merchant
      properties:
        merchant_name:
          type: string
          description: Merchant name
          example: Amazon.in
        merchant_subtitle:
          type: string
          description: Merchant subtitle or additional info
          nullable: true
        marketplace_seller:
          type:
          - string
          - 'null'
          description: Third-party seller on the marketplace
        seller_name:
          type: string
          description: Seller name
        brand:
          type:
          - string
          - 'null'
          description: Product brand. Set on only some offers, so often `null` or absent.
        product_name:
          type: string
          description: Product name as listed by merchant
          example: Nike Men's Court Vision Low Next Nature Shoes
        url:
          type: string
          description: Offer URL with attribution
          example: https://www.amazon.in/dp/B098F6QPLK?utm_source=chatgpt.com
        price:
          type: string
          description: Offer price
          example: $79.99
        details:
          type: string
          description: Stock and delivery information
          example: In stock online, Free delivery
        original_price:
          type: string
          description: Original price before discount
          nullable: true
        available:
          type: boolean
          description: Whether the product is available
          example: true
        checkoutable:
          type: boolean
          description: Whether the product can be checked out directly
          example: false
        is_digital:
          type: boolean
          description: Whether this is a digital product
          nullable: true
        checkout_payload:
          type: string
          description: Checkout payload data
          nullable: true
        checkout_image_urls:
          type: array
          description: Image URLs for checkout display
          items:
            type: string
          nullable: true
        shop_id:
          type: string
          description: Shop identifier
          nullable: true
        provider:
          type: string
          description: Data provider identifier
          example: p2
        price_details:
          $ref: '#/components/schemas/PriceDetails'
        tag:
          $ref: '#/components/schemas/OfferTag'
    GoogleGotoRequest:
      required:
      - url
      type: object
      properties:
        url:
          description: The Google redirect link to resolve, as an absolute URL. Must be a `google.com` or `www.google.com` link with a `/goto` or `/url` path — the form shipped as `redirectLink` beside every resolved link on Google Search, Google News, and AI Mode responses.
          type: string
          format: uri
          example: https://www.google.com/goto?url=CAESaQHrOzAVqzmLoOGwx_6OnzSPRKSyqmXD3yEDa0VIkUCfa5RKEaB9eIJOYz_M1y_VwKrr5jrSlrFlZlBUbe9DQXMPRUiSOrjBMQ78vpRZtXEhawDDabM58DDRHnv2f-XOQAWw-nwkup9ptQ
      additionalProperties: false
    InlineProduct:
      type: object
      description: Inline product reference that appeared in the response text, including pricing and offers
      properties:
        product:
          $ref: '#/components/schemas/ShoppingProduct'
        render_as:
          type: string
          description: How the product is rendered in the response
          enum:
          - inline
          - hero
          - block
          example: hero
    GoogleGotoResponse:
      required:
      - url
      type: object
      properties:
        url:
          description: The destination the redirect link points to
          type: string
          format: uri
          example: https://www.youtube.com/watch?v=pma08NXw8Ts&t=541
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Request validation failed
            details:
              type: array
              description: One entry per invalid field. Sent on request-body validation errors.
              items:
                type: object
                properties:
                  field:
                    type: string
                    example: prompt
                  message:
                    type: string
                    example: Prompt cannot be empty
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    PriceDetails:
      type: object
      description: Detailed price breakdown for an offer
      properties:
        display_price:
          type: string
          description: Formatted display price
          nullable: true
        base:
          type: string
          description: Base product price
          example: $79.99
        shipping:
          type: string
          description: Shipping cost
          nullable: true
        tax:
          type: string
          description: Tax amount
          nullable: true
        total:
          type: string
          description: Total price
          example: $79.99
    AiModeMonitorRequest:
      required:
      - prompt
      type: object
      properties:
        prompt:
          description: The prompt to send to AI Mode
          type: string
          minLength: 1
          maxLength: 10000
          example: What are the best laptops for programming?
        country:
          $ref: '#/components/schemas/CountryCode'
          description: Country/region code for localized response, using ISO 3166-1 alpha-2 country codes.
        gl:
          $ref: '#/components/schemas/GlParameter'
        hl:
          $ref: '#/components/schemas/HlParameter'
        location:
          description: 'Google canonical location name for geo-targeted results, in comma-separated format: ''City,Region,Country'' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside ''country'' for city-level precision. Mutually exclusive with ''uule'' — provide one or the other, not both. When both `location` and `uule` are omitted, cloro pins results to the country''s canonical location (e.g. `Portugal` for `PT`) where it has one; otherwise Google geolocates from the proxy''s exit IP.'
          type: string
          example: New York,New York,United States
        uule:
          description: Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both.
          type: string
          example: w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5
        device:
          description: Device type for search results
          type: string
          enum:
          - desktop
          - mobile
          default: desktop
          example: desktop
        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
            expandProducts:
              description: 'Fetch merchant offers for the product clusters in the response and return them as ''result.productResults''. Clusters are deduplicated across shopping cards and inline products, and expansion covers at most 6 per scrape. Paid add-on: +1 credit per cluster returned, up to +6 ([pricing](/guides/providers#ai-mode-additional-features)). Off by default.'
              type: boolean
              default: false
              example: true
            googleGoto:
              description: Ignored since 8th September 2026. Every redirect link now ships as `redirectLink` beside its destination, so both are returned without this flag. Requests still sending it behave as if it were absent.
              type: boolean
              default: false
              example: true
              deprecated: true
          default:
            html: false
            markdown: false
            expandProducts: false
          additionalProperties: false
      additionalProperties: false
      anyOf:
      - required:
        - country
      - required:
        - gl
    ConcurrentLimitError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: CONCURRENCY_LIMIT_EXCEEDED
            message:
              type: string
              example: Concurrency limit exceeded
            details:
              type: object
              properties:
                limit:
                  type: number
                  example: 10
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ShowcaseBackground:
      type: object
      description: Background styling for a product showcase
      properties:
        type:
          type: string
        primary:
          type: string
        secondary:
          type: string
    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://cdn.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:
                type: string
                example: find best hotels and restaurants in lisbon
            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: {}
    GeminiMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Gemini response data
          type: object
          properties:
            text:
              type: string
              description: Gemini's response text
              example: Quantum computing is a type of computation...
            markdown:
              type: string
              description: Gemini's response in Markdown format
              example: '**Quantum computing** is a type of computation...'
            html:
              type: string
              description: A URL to the full HTML of the response. Expires 24 hours after generation.
              example: https://cdn.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html
            sources:
              type: array
              description: Sources cited by Gemini
              items:
                type: object
                properties:
                  position:
                    type: integer
                    description: Position of the source in the list
                    example: 1
                  label:
                    type: string
                    description: Label or title of the source
                    example: Wikipedia - Quantum Computing
                  url:
                    type: string
                    description: URL of the source
                    example: https://en.wikipedia.org/wiki/Quantum_computing
                  description:
                    type: string
                    description: Description or snippet of the source
                    example: Quantum computing is a multidisciplinary field...
            citationPills:
              type: array
              description: 'Inline citation pills extracted from the Gemini answer. Each entry is one (pill, source) pair: when a chip cites N sources (Gemini''s `+N` analog or section-summary chips), the array contains N entries sharing the same `citationPillId` but with per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure. `label` is always present on the wire; it can be an empty string when the rail has no title for a source. 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 (for example `"Quantum computing — Wikipedia"`). Always present on the wire; may be an empty string when the rail has no title for this source — consumers should read `domain` / `url` for source identity in that case.
                    example: Quantum computing — Wikipedia
                  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://en.wikipedia.org/wiki/Quantum_computing
                  domain:
                    type: string
                    description: Host extracted from `url`, for grouping and display.
                    example: en.wikipedia.org
                  description:
                    type: string
                    description: Source description from the sources rail when Gemini ships one. Omitted when absent.
                    example: Quantum computing is a multidisciplinary field...
                  position:
                    type: integer
                    description: 1-based position of this source in the sibling `result.sources` array.
                    example: 1
              example:
              - label: Quantum computing — Wikipedia
                citationPillId: 1
                url: https://en.wikipedia.org/wiki/Quantum_computing
                domain: en.wikipedia.org
                description: Quantum computing is a multidisciplinary field...
                position: 1
              - label: IBM Quantum
                citationPillId: 1
                url: https://www.ibm.com/quantum
                domain: ibm.com
                position: 3
            places:
              type: array
              description: Place cards returned for lodging and local answers
              items:
                type: object
                required:
                - index
                - title
                - link
                properties:
                  index:
                    type: integer
                    description: Position index of the place in the results
                    example: 0
                  title:
                    type: string
                    description: Place name
                    example: Pullman Quay Grand Sydney Harbour
                  link:
                    type: string
                    format: uri
                    description: Google URL for the place
                    example: https://www.google.com/travel/search?q=Pullman+Quay+Grand+Sydney+Harbour
                  thumbnail:
                    type: string
                    format: uri
                    description: Place photo URL
                    example: https://lh3.googleusercontent.com/gps-cs-s/example
                  rating:
                    type: number
                    description: Star rating (0-5)
                    example: 4.4
                  reviews:
                    type: integer
                    description: Number of reviews
                    example: 1307
                  type:
                    type: string
                    description: Place type or category
                    example: 5-star hotel
                  description:
                    type: string
                    description: Short description of the place
                    example: Upscale hotel offering sophisticated suites, plus a restaurant, an indoor pool & a chic bar.
                  price:
                    type: string
                    description: Nightly price as Gemini displays it
                    example: $565
            shoppingCards:
              type: array
              description: Product cards Gemini shows on shopping answers, in display order. Field names follow AI Mode's `shoppingCards`. Omitted from `result` when the answer carries no product cards.
              items:
                type: object
                required:
                - position
                - title
                - productLink
                - productId
                properties:
                  position:
                    type: integer
                    description: 1-indexed rank across the `shoppingCards` array, in display order
                    example: 1
                  title:
                    type: string
                    description: Product title
                    example: ASICS Men's Novablast 5
                  productLink:
                    type: string
                    format: uri
                    description: Google Shopping URL for the product
                    example: https://google.com/search?q=ASICS+Men%27s+Novablast+5&prds=catalogid%3A15000182008314641842%2Cproductid%3A11413473167792520357&ibp=oshop
                  productId:
                    type: string
                    description: Google Shopping product ID
                    example: '11413473167792520357'
                  price:
                    type: object
                    description: Current price. For a range, `value` is the lowest price. For an installment offer, only `raw` is present
                    properties:
                      value:
                        type: number
                        description: Numeric price. Absent for an installment offer
                        example: 129.95
                      currency:
                        type: string
                        description: Currency symbol or code as displayed. Absent for an installment offer
                        example: $
                      raw:
                        type: string
                        description: Price text as Gemini displays it
                        example: $129.95
                  oldPrice:
                    type: object
                    description: Price before a discount, same shape as `price`. Absent when there is no discount
                    properties:
                      value:
                        type: number
                        description: Numeric price
                        example: 149.99
                      currency:
                        type: string
                        description: Currency symbol or code as displayed
                        example: $
                      raw:
                        type: string
                        description: Price text as Gemini displays it
                        example: $149.99
                  store:
                    type: string
                    description: Store that sells the product at `price`
                    example: Marathon Sports
                  storeLink:
                    type: string
                    format: uri
                    description: Direct URL of the product on the store's site
                    example: https://www.marathonsports.com/products/asics-mens-novablast-5
                  storeCount:
                    type: integer
                    description: Number of stores that sell the product. Gemini shows "& more" after the store name when it is above 1
                    example: 2
                  shipping:
                    type: string
                    description: Shipping cost as Gemini displays it
                    example: Free
                  deliveryTime:
                    type: string
                    description: Delivery time as Gemini displays it
                    example: Up to 5 days
                  rating:
                    type: number
                    description: Product rating (0-5). Absent for a product with no reviews
                    example: 4.8
                  reviews:
                    type: integer
                    description: Number of reviews
                    example: 11558
                  brand:
                    type: string
                    description: Product brand
                    example: ASICS
                  description:
                    type: string
                    description: Product description
                    example: The ASICS Novablast is a multi-talented running shoe...
                  thumbnail:
                    type: string
                    format: uri
                    description: Image URL that the card shows
                    example: https://encrypted-tbn1.gstatic.com/shopping?q=tbn:example
                  images:
                    type: array
                    description: All product image URLs. The first one is `thumbnail`
                    items:
                      type: string
                      format: uri
                    example:
                    - https://encrypted-tbn1.gstatic.com/shopping?q=tbn:example
                  catalogId:
                    type: string
                    description: Google Shopping catalog ID
                    example: '15000182008314641842'
                  gpcId:
                    type: string
                    description: Google Shopping product cluster ID
                    example: '1340101364570861215'
            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: {}
    CanceledError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: REQUEST_CANCELED
            message:
              type: string
              example: Request was canceled by client
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    OfferTag:
      type: object
      description: Promotional tag on an offer
      properties:
        text:
          type: string
          description: Tag text
          example: Best price
        tooltip:
          type: string
          description: Tag tooltip text
      nullable: true
    CountryCode:
      description: ISO 3166-1 alpha-2 country code.
      type: string
      enum:
      - AD
      - AE
      - AF
      - AG
      - AI
      - AL
      - AM
      - AO
      - AQ
      - AR
      - AS
      - AT
      - AU
      - AW
      - AX
      - AZ
      - BA
      - BB
      - BD
      - BE
      - BF
      - BG
      - BH
      - BI
      - BJ
      - BL
      - BM
      - BN
      - BO
      - BQ
      - BR
      - BS
      - BT
      - BV
      - BW
      - BY
      - BZ
      - CA
      - CC
      - CD
      - CF
      - CG
      - CH
      - CI
      - CK
      - CL
      - CM
      - CN
      - CO
      - CR
      - CU
      - CV
      - CW
      - CX
      - CY
      - CZ
      - DE
      - DJ
      - DK
      - DM
      - DO
      - DZ
      - EC
      - EE
      - EG
      - EH
      - ER
      - ES
      - ET
      - FI
      - FJ
      - FK
      - FM
      - FO
      - FR
      - GA
      - GB
      - GD
      - GE
      - GF
      - GG
      - GH
      - GI
      - GL
      - GM
      - GN
      - GP
      - GQ
      - GR
      - GS
      - GT
      - GU
      - GW
      - GY
      - HK
      - HM
      - HN
      - HR
      - HT
      - HU
      - ID
      - IE
      - IL
      - IM
      - IN
      - IO
      - IQ
      - IR
      - IS
      - IT
      - JE
      - JM
      - JO
      - JP
      - KE
      - KG
      - KH
      - KI
      - KM
      - KN
      - KP
      - KR
      - KW
      - KY
      - KZ
      - LA
      - LB
      - LC
      - LI
      - LK
      - LR
      - LS
      - LT
      - LU
      - LV
      - LY
      - MA
      - MC
      - MD
      - ME
      - MF
      - MG
      - MH
      - MK
      - ML
      - MM
      - MN
      - MO
      - MP
      - MQ
      - MR
      - MS
      - MT
      - MU
      - MV
      - MW
      - MX
      - MY
      - MZ
      - NA
      - NC
      - NE
      - NF
      - NG
      - NI
      - NL
      - 'NO'
      - NP
      - NR
      - NU
      - NZ
      - OM
      - PA
      - PE
      - PF
      - PG
      - PH
      - PK
      - PL
      - PM
      - PN
      - PR
      - PS
      - PT
      - PW
      - PY
      - QA
      - RE
      - RO
      - RS
      - RU
      - RW
      - SA
      - SB
      - SC
      - SD
      - SE
      - SG
      - SH
      - SI
      - SJ
      - SK
      - SL
      - SM
      - SN
      - SO
      - SR
      - SS
      - ST
      - SV
      - SX
      - SY
      - SZ
      - TC
      - TD
      - TF
      - TG
      - TH
      - TJ
      - TK
      - TL
      - TM
      - TN
      - TO
      - TR
      - TT
      - TV
      - TW
      - TZ
      - UA
      - UG
      - UM
      - US
      - UY
      - UZ
      - VA
      - VC
      - VE
      - VG
      - VI
      - VN
      - VU
      - WF
      - WS
      - XK
      - YE
      - YT
      - ZA
      - ZM
      - ZW
      example: US
    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
    ForbiddenError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - INSUFFICIENT_CREDITS
              example: INSUFFICIENT_CREDITS
            message:
              type: string
              example: Insufficient credits
            timestamp:
              type: string
              format: date-time
              example: '2025-01-15T12:00:00.000Z'
    ShoppingProduct:
      type: object
      description: Individual product information
      properties:
        title:
          type: string
          description: Product name
          example: Nike Court Vision Low Next Nature Shoes
        position:
          type: integer
          description: 1-indexed rank across all products in all shopping cards in the response (flat, not reset per card).
          example: 1
        url:
          type: string
          description: Product page URL
          example: https://www.amazon.in/Nike-Court-Vision-Shoes/dp/B098F6QPLK?utm_source=chatgpt.com
        description:
          type: string
          description: Product description
          example: Classic sneaker with modern comfort features
        price:
          type: string
          description: Current price
          example: $79.99
        featured_tag:
          type: string
          description: Product category or style tag
          example: stylish casual leather sneaker
        rating:
          type: number
          description: Product rating (0-5)
          example: 4.5
        num_reviews:
          type: integer
          description: Number of reviews
          example: 8703
        image_urls:
          type: array
          description: Product image URLs
          items:
            type: string
        id:
          type: string
          description: Product identifier
          example: prod_12345
        variants:
          description: Product variants (size, color, etc.)
        offers:
          type: array
          description: Shopping offers with pricing details from different merchants
          items:
            $ref: '#/components/schemas/ShoppingOffer'
        rating_grouped_citation:
          $ref: '#/components/schemas/RatingGroupedCitation'
        provider:
          type: string
          description: Data provider identifier
          example: deprecated
        providers:
          type: array
          description: List of data providers
          items:
            type: string
          example:
          - product_info
        product_lookup_key:
          type: object
          description: Key used to look up product updates
          properties:
            data:
              type: string
              description: JSON-encoded product lookup data
        product_lookup_data:
          type: object
          description: Structured product lookup query data
          properties:
            request_query:
              type: string
              description: Search query used for this product
            all_ids:
              type: object
              description: Provider-to-ID mapping
              additionalProperties:
                type: array
                items:
                  type: string
            metadata_sources:
              type: array
              items:
                type: string
        showcase_metadata:
          $ref: '#/components/schemas/ShowcaseMetadata'
        show_price_disclosure:
          type: boolean
          description: Whether to show price disclosure
          example: false
        analytics_meta:
          type: object
          description: Analytics metadata
          properties:
            product_event_uuid:
              type: string
              description: UUID for product analytics event
        metadata_sources:
          type: array
          description: Sources of product metadata
          items:
            type: string
          example:
          - p2
        product_event_uuid:
          type: string
          description: UUID for product event tracking
        generatedProductQuery:
          type: string
          description: Broad shopping query ChatGPT generated for this product (extracted from product_lookup_key.data). Useful for understanding the search intent behind the recommendation.
          example: best microwaves uk 2026 countertop inverter combi microwave
    ShowcaseSlot:
      type: object
      description: Single visual slot inside a product showcase
      properties:
        fit:
          type: string
        position:
          $ref: '#/components/schemas/ImagePosition'
        zoom:
          type: number
        placement:
          $ref: '#/components/schemas/SlotPlacement'
        imageBlendMode:
          type: string
    ImagePosition:
      type: object
      description: Pixel offset for image positioning within a slot
      properties:
        x:
          type: number
        y:
          type: number
      required:
      - x
      - y
    RatingGroupedCitation:
      type: object
      description: Rating source information with supporting websites
      properties:
        title:
          type: string
          description: Source title
          example: Nike Men's Court Vision Low Next Nature Shoes
        url:
          type: string
          description: Source URL
          example: https://www.amazon.in/dp/B098F6QPLK
        supporting_websites:
          type: array
          description: Array of supporting website references
          items:
            type: object
    GoogleNewsMonitorResponse:
      required:
      - success
      - result
      type: object
      properties:
        success:
          type: boolean
          example: true
        result:
          description: Google News results data
          type: object
          properties:
            newsResults:
              type: array
              description: News articles from Google News
              items:
                type: object
                properties:
                  position:
                    type: number
                    description: Position in news results (1-indexed)
                    example: 1
                  title:
                    type: string
                    description: Title of the news article
                    example: Major Climate Summit Reaches Historic Agreement
                  link:
                    type: string
                    description: URL of the news article
                    example: https://example.com/climate-summit-agreement
                  snippet:
                    type: string
                    description: Text snippet describing the article
                    example: World leaders agreed on new climate targets at the summit...
                  source:
                    type: string
                    description: News source/publisher name
                    example: The Guardian
                  date:
                    type: string
                    description: Publication date
                    example: 2 hours ago
                  page:
                    type: number
                    description: Page number this result appeared on (1-indexed)
                    example: 1
                  thumbnail:
                    type: string
                    description: Thumbnail image URL (if available)
                    example: https://example.com/images/climate-summit.jpg
                  redirectLink:
                    type: string
                    description: Google's `/goto` redirect for this link, in the absolute form `POST /v1/monitor/google/goto` accepts. Present only when Google served the link as a redirect — the sibling link field holds the destination cloro resolved it to.
                    example: https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk
            html:
              type: array
              description: Raw HTML from Google News pages (if requested)
              items:
                type: string
                format: uri
              example:
              - https://cdn.cloro.dev/results/a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6/page-1.html
    GoogleMapPlace:
      description: Place card from a Google AI answer that Google geo-tagged
      allOf:
      - $ref: '#/components/schemas/GooglePlaceBase'
      - type: object
        required:
        - placeId
        - link
        - gpsCoordinates
        properties:
          link:
            type: string
            format: uri
            description: Google Maps URL for the place
            example: https://maps.google.com/?cid=11340480041048787817
          gpsCoordinates:
            type: object
            description: Geographic coordinates of the place
            properties:
              latitude:
                type: number
                description: Latitude coordinate
                example: 40.7831
              longitude:
                type: number
                description: Longitude coordinate
                example: -73.9712
    SlotPlacement:
      type: object
      description: Percent-based placement of a showcase slot within its container
      properties:
        leftPercent:
          type: number
        topPercent:
          type: number
        widthPercent:
          type: number
        heightPercent:
          type: number
    GooglePlaceBase:
      type: object
      description: Fields shared by the place and map entries of a Google AI answer
      required:
      - title
      - index
      properties:
        title:
          type: string
          description: Place name
          example: Gion District
        index:
          type: integer
          description: Position index of the place in the results
          example: 0
        thumbnail:
          type: string
          format: uri
          description: Place thumbnail image URL
          example: https://lh5.googleusercontent.com/p/example
        rating:
          type: number
          description: Star rating (0-5)
          example: 4.5
        reviews:
          type: integer
          description: Number of reviews
          example: 2900
        type:
          type: string
          description: Place type or category
          example: Tourist attraction
        address:
          type: string
          description: Full postal address, as Google gives it on the card's Directions link
          example: 510 Atlantic Ave, Boston, MA 02210
        status:
          type: string
          description: Operating status
          example: Open now
        placeId:
          type: string
          description: Google Knowledge Graph ID for the place. A place and its `map` entry share it. Omitted when Google did not geo-tag the card.
          example: /g/1tglgvbk
        phone:
          type: string
          description: Phone number from the card's Call button, formatted as Google ships it for the locale. Omitted when the card has no Call button.
          example: '+16177471000'
        website:
          type: string
          format: uri
          description: Business website from the card's Website button. Omitted when the card has no Website button.
          example: https://www.thedagnyboston.com/
    AuthenticationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        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'
    ShowcaseImage:
      type: object
      description: Image rendered as the hero of a product showcase
      properties:
        url:
          type: string
        width:
          type: number
        height:
          type: number
      required:
      - url
  headers:
    XRateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
        example: 1000
    XRateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 997
    XLatencyMs:
      description: Milliseconds the API spent on the request, from arrival to the start of the response. Excludes network transit.
      schema:
        type: integer
        example: 3420
    XRequestId:
      description: Unique ID for this request. Support uses it to find your request.
      schema:
        type: string
        format: uuid
        example: b0864943-5d45-4796-bc64-f052661256f0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: cloro API key as a bearer token. One key grants every endpoint in this spec; per-key scopes are not available, so a client cannot request a narrower permission. Keys are created and revoked in the [dashboard](https://dashboard.cloro.dev/api-keys).
x-refined-from:
- cloro-dev-openapi.json
- cloro-dev-openapi.yml