POST
/
v1
/
run
Monitor AI Responses
curl --request POST \
  --url https://api.cloro.com/v1/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "What do you know about Acme Corp?",
  "model": "CHATGPT",
  "country": "US"
}'
{
  "success": true,
  "result": "Acme Corp is a technology company known for its innovative software solutions...",
  "metadata": {
    "provider": "chatgpt",
    "region": "US",
    "response_time": 2.1,
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

​
Overview

The Run endpoint allows you to track and monitor what AI providers say about your brand, products, or any topic across various regions. This endpoint processes your prompts through AI models and returns their responses for analysis.

​
Authentication

This endpoint requires authentication using a Bearer token in the Authorization header. 
Authorization: Bearer sk_live_1234567890abcdef1234567890abcdef

​
Request Body

​
prompt
string
required
The prompt to send to the AI model. Must be between 1 and 10,000 characters.
​
model
string
required
The AI provider to monitor. Currently supported:
  • CHATGPT: OpenAI’s ChatGPT
​
country
string
Optional country code for localized monitoring using ISO 3166-1 alpha-2 format (e.g., “US”, “GB”, “JP”, “AU”, “DE”). Defaults to “US”. The API supports 254 countries and territories. See the complete list of supported country codes below.

​
Response

​
success
boolean
Indicates whether the request was successful
​
result
string
The AI provider’s response to your prompt
​
metadata
object
Additional information about the response
​
error
string
Error message if the request failed (only present when success is false)

​
Error Responses

The API returns standard HTTP status codes to indicate the success or failure of requests:
  • 200 - Success
  • 400 - Bad Request (validation error)
  • 401 - Unauthorized (invalid API key)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error
Error Response
{
  "success": false,
  "error": "Request validation failed",
  "details": [
    {
      "field": "prompt",
      "message": "Prompt cannot be empty"
    }
  ]
}

​
Rate Limiting

This endpoint is subject to rate limiting:
  • 1,000 requests per hour
Rate limit information is included in response headers:
  • X-RateLimit-Limit: Total number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​
Supported Country Codes

The API accepts ISO 3166-1 alpha-2 country codes for the country parameter. All 254 standard country codes are supported. Common Examples:
  • US - United States
  • GB - United Kingdom
  • CA - Canada
  • AU - Australia
  • DE - Germany
  • FR - France
  • JP - Japan
  • CN - China
  • IN - India
  • BR - Brazil
For the complete list of supported codes, see the official ISO 3166-1 alpha-2 reference.

​
Best Practices

  1. Craft Specific Prompts: Be specific about what you want to monitor for more accurate tracking
  2. Monitor Consistently: Set up regular monitoring intervals to track changes over time
  3. Compare Providers: Monitor the same prompt across different AI providers to identify variations
  4. Track Regions: Monitor responses across different regions to understand geographical variations
  5. Implement Caching: Cache responses when appropriate to reduce API calls and costs
  6. Error Handling: Implement robust error handling and retry logic for failed 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 AI responses

The body is of type object.

Response

Successful monitoring response

The response is of type object.