
# Building a real-time streaming task manager with Parallel
Build a task streaming playground that showcases Parallel's Task API with real-time Server-Sent Events (SSE).

This guide demonstrates how to build a complete task streaming playground that showcases Parallel's Task API[Parallel's Task API]($https://docs.parallel.ai/task-api/task-quickstart) with real-time Server-Sent Events (SSE). By the end, you'll have a full-featured application that creates tasks, streams their execution progress, and displays results as they arrive. This can be helpful for developers building with the Task API, demonstrating how to recreate the user interfaces in our Playground[Playground]($https://platform.parallel.ai).
Complete demo available at: https://oss.parallel.ai/tasks-sse/[https://oss.parallel.ai/tasks-sse/]($https://oss.parallel.ai/tasks-sse/)
## Key Features
- - Task Manager for All Processors: From lite ($5/1K) to ultra8x ($2400/1K)
- - Output Schemas: Text, JSON and Auto Schema
- - Source Policy: Domain inclusion and exclusion
- - Webhooks: HTTP notifications on task completion
- - Streaming events view for each Task in the Task Manager
- - OAuth flow for easy testing
## The Architecture
The task streaming playground we're building includes:
- - OAuth2 authentication with Parallel's identity provider
- - A comprehensive task creation form supporting all processor types and output schemas
- - Real-time task progress streaming with Server-Sent Events
- - Task history management with persistent localStorage
- - Auto-reconnection for resilient streaming connections
- - Rich event visualization with progress indicators and final outputs
## Our technology stack
- - Parallel Task API for task execution
- - Parallel OAuth Provider for secure authentication
- - Server-Sent Events[Server-Sent Events]($https://docs.parallel.ai/task-api/features/task-sse) for real-time streaming
- - Cloudflare Workers[Cloudflare Workers]($https://workers.cloudflare.com/) for deployment and CORS proxying
- - Pure HTML/JavaScript/CSS for maximum compatibility
## Why this architecture
### Stateless Streaming Design
The key insight behind this implementation is that you don't need to maintain any backend state during streaming. The Parallel Task API's SSE endpoint provides the complete current state every time you connect, including:
- - All previous events that occurred before connecting
- - The latest progress statistics
- - Current task status and metadata
- - Final outputs when tasks complete
This stateless design means your backend can be incredibly simple - just a CORS proxy. All the complexity lives in the well-tested Parallel infrastructure.
### OAuth2 with PKCE Security
For production-ready authentication, we implement the complete OAuth2 flow with PKCE (Proof Key for Code Exchange):
- Dynamic Client Registration: Register OAuth client on-demand
- PKCE Challenge: Generate cryptographically secure code challenge
- Authorization Redirect: Send user to Parallel's OAuth server
- Token Exchange: Securely exchange authorization code for access token
- Persistent Storage: Store token in localStorage for session management
This provides enterprise-grade security without requiring pre-registration of OAuth clients.
## Implementation
### Real-Time Event Streaming
Server-Sent Events (SSE) provide the real-time updates for this Task manager that helps end-users understand the progress of the Parallel Task API. This is especially helpful for longer-running processors, like Pro and above. Unlike traditional polling approaches that repeatedly ask "are you done yet?", SSE creates a persistent connection that streams updates as they happen. However, implementing SSE correctly in the browser requires handling several complex challenges.
#### Why Manual SSE Implementation?
While browsers provide a built-in `EventSource` API for SSE, it has a critical limitation: **you cannot set custom headers**. Since Parallel's API requires authentication via the `x-api-key` header, we must implement SSE manually using the Fetch API and ReadableStreams.
SSE data arrives as a continuous stream of bytes, not discrete messages. Network packets can split messages in unpredictable ways:
Our implementation handles this with a streaming buffer pattern:
This pattern ensures we never lose data or attempt to parse incomplete JSON, regardless of how network packets arrive.
#### Resilient Connection Management
Task execution can take anywhere from seconds to 30+ minutes. Network connections inevitably drop during long operations, so robust reconnection logic is essential:
**Key resilience features:**
- - Status-based reconnection: Only retry for tasks that might still be generating events
- - Exponential backoff: 2-second delays prevent overwhelming the server
- - Attempt limiting: Prevents infinite retry loops on permanent failures
- - Stateless recovery: Each reconnection gets the complete current state
#### Understanding the Event Stream Format
Parallel's SSE stream follows the standard Server-Sent Events specification. Each event is prefixed with `data: ` and terminated with double newlines. The implementation strips the prefix and parses the JSON payload:
#### Event Type Taxonomy
The stream delivers several categories of events, each serving a different purpose:
- - `task_run.state`: Core lifecycle events (queued → running → completed/failed)
- - `task_run.progress_stats`: Quantitative metrics (sources found, pages read, tokens used)
- - `task_run.progress_msg.*`: Qualitative updates with timestamped reasoning steps
- - `task_run.progress_msg.reasoning`: AI thought process
- - `task_run.progress_msg.search`: Search query generation
- - `task_run.progress_msg.analysis`: Content analysis steps
- - `error`: Exception conditions with detailed error messages
This rich event taxonomy enables granular UI updates - progress bars for stats, reasoning displays for AI thinking, and error handling for failures.
#### Event Visualization and UI
The frontend renders different event types with appropriate styling:
### CORS Proxy Worker
A simple worker solves a fundamental web security challenge. Modern browsers implement the Same-Origin Policy, which prevents JavaScript running on `yourdomain.com` from making direct API calls to `api.parallel.ai`. This security feature protects users from malicious websites, but it also blocks legitimate applications from accessing external APIs.
Traditional solutions involve building a full backend API server that handles authentication, request validation, and response transformation. Instead, we use a much simpler proxy pattern that acts as a transparent middleman:
- - Path Rewriting: `/tasks-sse/api/v1/tasks/runs` becomes `https://api.parallel.ai/v1/tasks/runs`
- - Header Preservation: All original headers (including `x-api-key`) are forwarded
- - CORS Headers: Added to all responses to enable browser access
- - Static Serving: The same worker serves the HTML frontend
### OAuth Authentication
The OAuth flow implementation handles dynamic client registration, as well as the complete PKCE security protocol:
## Resources
- - App Source Code[App Source Code]($https://github.com/parallel-web/parallel-cookbook/tree/main/typescript-recipes/parallel-tasks-sse)
- - Live App Example[Live App Example]($https://oss.parallel.ai/tasks-sse/)
- - Parallel SSE Documentation[Parallel SSE Documentation]($https://docs.parallel.ai/task-api/features/task-sse)
By Parallel
October 6, 2025





























