Tracking Progress

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
});

Getting started

Rest API

SDKs

1. Initiating a Check Job

Job ID Requirements

For /check (JSON)

2. Connecting to WebSocket

3. Progress Message Format

Message Structure

4. Client Implementation Example (Node.js)

​1. Initiating a Check Job

​Job ID Requirements

​For /check (JSON)

​2. Connecting to WebSocket

​3. Progress Message Format

​Message Structure

​4. Client Implementation Example (Node.js)

1. Initiating a Check Job

Job ID Requirements

For /check (JSON)

2. Connecting to WebSocket

3. Progress Message Format

Message Structure

4. Client Implementation Example (Node.js)