Monitor AI Responses

​

Overview

​

Example Response

{
  "success": true,
  "result": {
    "markdown": "The **best EVs** vary depending on what you value most: range, performance, price, or features...",
    "html": "<p data-start=\"0\" data-end=\"276\">The <strong>best EVs</strong> vary depending on what you value most...</p>",
    "links": [
      {
        "position": 0,
        "label": "Consumer Reports: Best Electric Cars 2025",
        "url": "https://www.consumerreports.org/cars/evs/"
      },
      {
        "position": 1,
        "label": "Edmunds Review: Tesla Model 3",
        "url": "https://www.edmunds.com/tesla/model-3/"
      },
      {
        "position": 2,
        "label": "MotorTrend: Lucid Air",
        "url": "https://www.motortrend.com/cars/lucid/air/"
      }
    ]
  }
}

• Markdown format: Complete response with formatting preserved, including headings, bold text, lists, and links
• HTML format: Fully formatted HTML with data attributes for position tracking and proper styling
• Links array: All extracted links with their positions, labels, and URLs for easy reference

​

Error Responses

​

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 (concurrency limit exceeded)
• 499 - Client Closed Request (request was canceled)
• 500 - Internal Server Error
• 502 - Bad Gateway (external service error)

​

Error Response Format

{
  "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"
    }
  ]
}

• prompt: “Prompt cannot be empty” (min 1 character)
• prompt: “Prompt is too long (max 10,000 characters)”
• model: “Invalid enum value” (must be “CHATGPT”)
• country: “Invalid country code” (must be valid ISO 3166-1 alpha-2 code)

​

401 Unauthorized - Authentication Errors

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

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

{
  "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

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

{
  "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 - Concurrent Limit Exceeded

{
  "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"
}

​

500 Internal Server Error

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

{
  "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 Limiting

• 10 concurrent requests per user

• 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

• Maximum credits: 10,000 per account
• Cost: 1 credit per successful request (200 status only)

• X-Credits-Remaining: Number of credits remaining in your account (out of 10,000)
• X-Credits-Charged: Number of credits charged for this request (always 1 for successful requests)

​

Supported Country Codes

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

​

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