Tracking Progress
Learn how to monitor your sticker generation jobs in real-time.
Because Sticker Maker uses an async-first architecture, you need a way to track the status of your jobs. We provide three methods to suit different use cases.
Comparison
| Method | Latency | Best For | Complexity |
|---|---|---|---|
| WebSocket | Ultra-low (<50ms) | Real-time UI, Progress Bars | Medium |
| Server-Sent Events (SSE) | Low (<100ms) | Simple real-time updates | Low |
| Polling | High (1-2s) | Simple scripts, cron jobs | Very Low |
Method 1: WebSocket (Recommended)
WebSockets provide a persistent, bidirectional connection. This is the most efficient way to get real-time updates for your UI.
Endpoint
wss://api.stickermaker.dev/api/v1/jobs/:jobId/progress/ws
Implementation
const jobId = "job_abc123";
const ws = new WebSocket(
`wss://api.stickermaker.dev/api/v1/jobs/${jobId}/progress/ws`,
);
ws.onopen = () => {
console.log("Connected to progress stream");
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === "progress") {
console.log(`Progress: ${data.value}%`);
} else if (data.type === "completed") {
console.log("Sticker Ready:", data.result.url);
ws.close();
}
};Event Types
initial_state: Sent immediately upon connection.progress: Sent whenever the progress percentage changes.step_change: Sent when the job moves to a new processing step (e.g., "removing_bg" -> "applying_effects").completed: Sent when the job is finished.failed: Sent if an error occurs.
Method 2: Server-Sent Events (SSE)
SSE is a simpler alternative to WebSockets that works over standard HTTP. It's uni-directional (server to client) and easier to implement in some environments.
Endpoint
GET https://api.stickermaker.dev/api/v1/jobs/:jobId/progress/stream
Implementation
const jobId = "job_abc123";
const eventSource = new EventSource(
`https://api.stickermaker.dev/api/v1/jobs/${jobId}/progress/stream`,
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log("Update:", data);
};
eventSource.addEventListener("completed", (event) => {
const data = JSON.parse(event.data);
console.log("Done:", data.url);
eventSource.close();
});Method 3: Polling
Polling involves repeatedly making HTTP requests to check the status. While less efficient, it is robust and easy to implement without special libraries.
Endpoint
GET https://api.stickermaker.dev/api/v1/jobs/:jobId
Implementation
async function pollJob(jobId) {
const pollInterval = 2000; // 2 seconds
while (true) {
const response = await fetch(
`https://api.stickermaker.dev/api/v1/jobs/${jobId}`,
);
const data = await response.json();
if (data.status === "completed") {
return data.result;
}
if (data.status === "failed") {
throw new Error(data.error.message);
}
// Wait before next check
await new Promise((r) => setTimeout(r, pollInterval));
}
}Rate Limiting: Aggressive polling (e.g., every 100ms) may trigger rate limits. We recommend an interval of at least 1-2 seconds.