Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clearproxy.io/llms.txt

Use this file to discover all available pages before exploring further.

This API supports real-time progress tracking for proxy checking jobs using client-generated Job IDs.

​
1. Initiating a Check Job

To use real-time tracking, you must generate a unique jobId on the client side and provide it to the API.

​
Job ID Requirements

  • Format: 3-64 characters, alphanumeric, underscores (_), or hyphens (-).
  • Uniqueness: A jobId can only be used by one active request at a time. If you use an ID that is already in progress, the API will return a 409 Conflict error.
  • Reuse: You can reuse the same ID once the previous job associated with it has completed or failed.

​
For /check (JSON)

Include the jobId in the JSON request body. 
{
  "proxies": ["1.2.3.4:8080", ...],
  "jobId": "my_unique_job_id_123"
}

​
2. Connecting to WebSocket

Connect to the WebSocket endpoint before or during the HTTP request to start receiving updates. Endpoint: 
ws://api.clearproxy.io/ws?jobId=<YOUR_JOB_ID>
Example: ws://api.clearproxy.io/ws?jobId=my_unique_job_id_123

​
3. Progress Message Format

The WebSocket server sends JSON messages for every major step.

​
Message Structure

{
  "jobId": "my_unique_job_id_123",
  "status": "in_progress",          // "in_progress", "completed", "failed"
  "currentStep": "proxy_check_batch_5_of_10",
  "stepsCompleted": ["validating", "checking_balance"],
  "progress": 35,                   // Percentage (0-100)
  "eta": "~1s",                    // Estimated Time Remaining
  "details": {                      // Step-specific details
    "message": "Finished Verifying Batch 61 (Working: 100, Failed: 900)",
    "batches_done": 43,
    "working_so_far": 1234
  },
  "timestamp": "2026-01-20T12:00:00.000Z"
}

​
4. Client Implementation Example (Node.js)

import WebSocket from 'ws';
import axios from 'axios';

const myJobId = 'client_job_' + Date.now();

// 1. Connect to WebSocket
const ws = new WebSocket(`ws://api.clearproxy.io/ws?jobId=${myJobId}`);

ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log(`[${event.progress}%] ${event.details.message}`);
});

// 2. Start Request
axios.post('https://api.clearproxy.io/check', {
  proxies: ['...'],
  jobId: myJobId
});