> ## 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.

# Tracking Progress

> Real-time progress tracking for proxy checking jobs

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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```javascript theme={null}
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
});
```