Extract ChatGPT

Monitor ChatGPT Responses

curl --request POST \
  --url https://api.cloro.dev/v1/monitor/chatgpt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "What do you know about Acme Corp?",
  "country": "US",
  "include": {
    "markdown": true,
    "rawResponse": true,
    "searchQueries": true
  }
}'

{
  "success": true,
  "result": {
    "text": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.",
    "sources": [
      {
        "position": 1,
        "url": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com",
        "label": "Rippling",
        "description": "12 Best AI Recruiting Tools For HR in 2025 | Rippling"
      },
      {
        "position": 2,
        "url": "https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com",
        "label": "Index.dev",
        "description": "7 Best AI Recruiting Software for Hiring Managers in 2025"
      },
      {
        "position": 3,
        "url": "https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com",
        "label": "SelectSoftware Reviews",
        "description": "10+ Best AI Recruiting Software for 2025: Expert Reviews + Pricing"
      }
    ],
    "html": "<div class=\"markdown\"><p data-start=\"0\" data-end=\"120\">The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:</p><h3 data-start=\"122\" data-end=\"155\">🐾 Acme Corporation in Fiction</h3><p data-start=\"156\" data-end=\"250\">The Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.</p></div>",
    "markdown": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.",
    "rawResponse": [
      {
        "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": [
      "What is Acme Corporation?",
      "Acme Corp company overview",
      "Acme Corporation products and services"
    ],
    "model": "gpt-5"
  }
}

POST

monitor

chatgpt

Monitor ChatGPT Responses

curl --request POST \
  --url https://api.cloro.dev/v1/monitor/chatgpt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "What do you know about Acme Corp?",
  "country": "US",
  "include": {
    "markdown": true,
    "rawResponse": true,
    "searchQueries": true
  }
}'

{
  "success": true,
  "result": {
    "text": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.",
    "sources": [
      {
        "position": 1,
        "url": "https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com",
        "label": "Rippling",
        "description": "12 Best AI Recruiting Tools For HR in 2025 | Rippling"
      },
      {
        "position": 2,
        "url": "https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com",
        "label": "Index.dev",
        "description": "7 Best AI Recruiting Software for Hiring Managers in 2025"
      },
      {
        "position": 3,
        "url": "https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com",
        "label": "SelectSoftware Reviews",
        "description": "10+ Best AI Recruiting Software for 2025: Expert Reviews + Pricing"
      }
    ],
    "html": "<div class=\"markdown\"><p data-start=\"0\" data-end=\"120\">The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:</p><h3 data-start=\"122\" data-end=\"155\">🐾 Acme Corporation in Fiction</h3><p data-start=\"156\" data-end=\"250\">The Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.</p></div>",
    "markdown": "The name \"Acme Corporation\" is used in various contexts, both fictional and real. Here's an overview:\n\n🐾 Acme Corporation in Fiction\nThe Acme Corporation is a fictional company featured prominently in Warner Bros. cartoons, particularly the Road Runner/Wile E. Coyote series.",
    "rawResponse": [
      {
        "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": [
      "What is Acme Corporation?",
      "Acme Corp company overview",
      "Acme Corporation products and services"
    ],
    "model": "gpt-5"
  }
}

Overview

The ChatGPT endpoint allows you to extract structured data from ChatGPT about your brand, products, or any topic across various regions. This endpoint processes your prompts through ChatGPT and returns parsed responses with sources & citations.

Request Parameters

Required Parameters

prompt (string): The prompt to send to ChatGPT (1-10,000 characters)

Optional Parameters

country (string): Optional country/region code for localized data extraction. Defaults to "US"
include (object): Optional flags for including additional response formats
- markdown (boolean): Include markdown-formatted response in the result. Defaults to false
- rawResponse (boolean): Include ChatGPT’s raw API response (useful for debugging or advanced parsing). Defaults to false
- searchQueries (boolean): Include the search queries ChatGPT used to generate the response. Defaults to false

Response Format Options

By default, all responses include both text and HTML formats. You can optionally include markdown, the raw provider response, or search queries:

Parameter	Default	Description	Use cases	Cost
`include.markdown`	`false`	Include markdown-formatted response in the result	Documentation, blogs, content management	5 credits
`include.rawResponse`	`false`	Include ChatGPT’s raw response payload (as returned by the provider)	Debugging, custom parsing, auditing provider-level details	7 credits
`include.searchQueries`	`false`	Include the search queries ChatGPT used to generate the response	SEO analysis, keyword research, content strategy	7 credits

Example Usage

Basic Request

{
  "prompt": "What do you know about Acme Corp?"
}

Request with Additional Formats

{
  "prompt": "What do you know about Acme Corp?",
  "country": "US",
  "include": {
    "rawResponse": true,
    "searchQueries": true
  }
}

Response Schema

All successful responses include these fields:

Field	Type	Description
`success`	boolean	Always `true` for successful responses
`result.text`	string	ChatGPT’s response text
`result.sources`	array	Array of sources referenced in the response
`result.html`	string	ChatGPT’s response formatted in HTML (always included)
`result.markdown`	string	ChatGPT’s response formatted in Markdown (included when `include.markdown` is true)
`result.rawResponse`	array	Array of ChatGPT’s streamed response events (included when `include.rawResponse` is true)
`result.searchQueries`	array	Array of search queries ChatGPT used to generate the response (included when `include.searchQueries` is true)
`result.model`	string	The ChatGPT model used to generate the response

Error Responses

The API returns standard HTTP status codes to indicate the success or failure of requests. All error responses follow a consistent format with an error object containing a code, message, details, and timestamp.

Status Codes

200 - Success
400 - Bad Request (validation error)
401 - Unauthorized (authentication error)
403 - Forbidden (insufficient permissions or credits)
404 - Not Found (route not found)
409 - Conflict (resource conflict)
429 - Too Many Requests
499 - Client Closed Request (request was canceled)
500 - Internal Server Error
502 - Bad Gateway (external service error)

Error Response Format

All error responses follow this structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional context-specific information
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Common Error Responses

400 Bad Request - Validation Error

{
  "success": false,
  "error": "Request validation failed",
  "details": [
    {
      "field": "prompt",
      "message": "Prompt cannot be empty"
    }
  ]
}

Validation Errors

Field	Error	Description
`prompt`	”Prompt cannot be empty”	Must be 1-10,000 characters
`prompt`	”Prompt is too long”	Exceeds 10,000 character limit
`country`	”Invalid country code”	Must be valid ISO 3166-1 alpha-2 code
`include.markdown`	”Expected boolean”	Must be `true` or `false`
`include.rawResponse`	”Expected boolean”	Must be `true` or `false`
`include.searchQueries`	”Expected boolean”	Must be `true` or `false`

401 Unauthorized - Authentication Errors

Missing API Key

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Missing or invalid API key",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Invalid API Key Format

{
  "error": {
    "code": "INVALID_API_KEY_FORMAT",
    "message": "Invalid API key format",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Invalid or Expired API Key

{
  "error": {
    "code": "INVALID_OR_EXPIRED_API_KEY",
    "message": "Invalid or expired API key",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

403 Forbidden - Permission or Credits Error

Insufficient Permissions

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Insufficient permissions",
    "details": {
      "requiredScopes": ["read:monitor", "write:monitor"]
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Insufficient Credits

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

404 Not Found - Route Error

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Route not found",
    "details": {
      "id": "/v1/invalid-endpoint"
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "CONCURRENT_LIMIT_EXCEEDED",
    "message": "Concurrent limit exceeded",
    "details": {
      "limit": 10
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

499 Client Closed Request

{
  "success": false,
  "error": "Request was canceled"
}

This occurs when the client closes the connection before the request completes.

500 Internal Server Error

Maximum Retries Exceeded

{
  "success": false,
  "error": "Maximum retries exceeded"
}

Generic Internal Error

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal server error",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

502 Bad Gateway - External Service Error

{
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "External service error: OpenAI",
    "details": {
      "service": "OpenAI"
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Concurrency Information

Concurrency information is included in response headers:

X-Concurrent-Limit: Maximum number of concurrent requests allowed
X-Concurrent-Current: Current number of concurrent requests
X-Concurrent-Remaining: Number of remaining concurrent slots available

Credits System

This endpoint uses a credit-based billing system:

Credit limit: Based on your purchased package
Base cost: 5 credits
Additional costs: +2 credits only when include.rawResponse or include.searchQueries are successfully retrieved

Note: If include.rawResponse or include.searchQueries are requested but not successfully retrieved, only the base 5 credits are charged. Credit information is included in response headers:

X-Credits-Remaining: Number of credits remaining in your account
X-Credits-Charged: Number of credits charged for this request (base cost + any successful add-ons)

Supported Country Codes

The API accepts ISO 3166-1 alpha-2 country codes for the country parameter to extract data from different regions. For a complete list of supported country codes, see the Countries endpoint. Common Examples:

US - United States
GB - United Kingdom
CA - Canada
AU - Australia
DE - Germany
FR - France
JP - Japan
CN - China
IN - India
BR - Brazil

Best Practices

Response Format Selection

Choose the right format based on your use case:

Format	Best For
Text + HTML	Web display, position tracking, rich formatting
+ Markdown	Documentation, blogs, CMS integration
+ Search Queries	SEO analysis, keyword research
+ Raw Response	Debugging, custom parsing

General Guidelines

Craft Specific Prompts: Be specific about what you want to extract for more accurate structured data from ChatGPT
Extract Consistently: Set up regular extraction intervals to track changes in ChatGPT responses over time
Track Regions: Extract responses across different regions to understand geographical ChatGPT behavior differences
Use Search Queries: Enable include.searchQueries to understand what terms ChatGPT researched to generate its response
Implement Caching: Cache structured responses when appropriate to reduce API calls and costs
Error Handling: Implement robust error handling and retry logic for failed extraction requests

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request parameters for monitoring ChatGPT responses

prompt

string

required

The prompt to send to ChatGPT

Required string length: 1 - 10000

Example:

"What do you know about Acme Corp?"

country

string

default:US

Optional country/region code for localized monitoring

Example:

"US"

include

object

Optional flags for including additional response formats

Show child attributes

Example:

{
  "markdown": true,
  "rawResponse": true,
  "searchQueries": true
}

Response

successful ChatGPT monitoring response

success

boolean

required

Example:

true

result

object

required

ChatGPT's response data

Show child attributes

Extract AI model List of countries

⌘I

Product

Documentation

API Reference

Overview

Request Parameters

Required Parameters

Optional Parameters

Response Format Options

Example Usage

Basic Request

Request with Additional Formats

Response Schema

Error Responses

Status Codes

Error Response Format

Common Error Responses

400 Bad Request - Validation Error

Validation Errors

401 Unauthorized - Authentication Errors

403 Forbidden - Permission or Credits Error

404 Not Found - Route Error

429 Too Many Requests

499 Client Closed Request

500 Internal Server Error

502 Bad Gateway - External Service Error

Concurrency Information

Credits System

Supported Country Codes

Best Practices

Response Format Selection

General Guidelines

Authorizations

Body

Response

Product

Documentation

API Reference

​Overview

​Request Parameters

​Required Parameters

​Optional Parameters

​Response Format Options

​Example Usage

​Basic Request

​Request with Additional Formats

​Response Schema

​Error Responses

​Status Codes

​Error Response Format

​Common Error Responses

​400 Bad Request - Validation Error

​Validation Errors

​401 Unauthorized - Authentication Errors

​403 Forbidden - Permission or Credits Error

​404 Not Found - Route Error

​429 Too Many Requests

​499 Client Closed Request

​500 Internal Server Error

​502 Bad Gateway - External Service Error

​Concurrency Information

​Credits System

​Supported Country Codes

​Best Practices

​Response Format Selection

​General Guidelines

Authorizations

Body

Response

Overview

Request Parameters

Required Parameters

Optional Parameters

Response Format Options

Example Usage

Basic Request

Request with Additional Formats

Response Schema

Error Responses

Status Codes

Error Response Format

Common Error Responses

400 Bad Request - Validation Error

Validation Errors

401 Unauthorized - Authentication Errors

403 Forbidden - Permission or Credits Error

404 Not Found - Route Error

429 Too Many Requests

499 Client Closed Request

500 Internal Server Error

502 Bad Gateway - External Service Error

Concurrency Information

Credits System

Supported Country Codes

Best Practices

Response Format Selection

General Guidelines