> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xerobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time Stream

> Server-Sent Events (SSE) endpoint that streams real-time progress updates during a full speed test.

**Event Types:**
- `ping`: Ping test starting/completed
- `jitter`: Jitter test completed
- `download`: Download test starting/completed
- `upload`: Upload test starting/completed
- `finish`: Test completed with all results
- `error`: Test failed with error details

**Event Data:**
- `status`: Test phase status (starting/completed)
- `result`: Test result value
- `progress`: Overall test progress (0-100%)

**Implementation Example:**
```javascript
const eventSource = new EventSource(
  'https://api.hixbe.com/speedtest/stream',
  { headers: { 'Xerobi-Version': '2.0.0' } }
);

eventSource.addEventListener('ping', (e) => {
  const data = JSON.parse(e.data);
  console.log('Ping:', data.result, 'ms');
  updateProgress(data.progress);
});

eventSource.addEventListener('finish', (e) => {
  const data = JSON.parse(e.data);
  console.log('Complete:', data.result);
  eventSource.close();
});

eventSource.addEventListener('error', (e) => {
  console.error('Error:', e.data);
  eventSource.close();
});
```

**Use Cases:**
- Real-time UI updates
- Progress bars
- Live test monitoring
- Interactive dashboards

**Note**: Keep connection open until 'finish' or 'error' event received.

Server-Sent Events stream for real-time test progress monitoring and status updates.


## OpenAPI

````yaml GET /stream
openapi: 3.1.0
info:
  title: Xerobi Speed Test API
  description: >-
    A comprehensive network speed testing API with advanced metrics, real-time
    progress tracking, result history, and comparative analysis.


    ## Overview


    The Xerobi Speed Test API provides powerful network performance testing
    capabilities:


    - **Basic Metrics**: Individual tests for ping, jitter, download, and upload
    speeds

    - **Advanced Tests**: Multi-file testing for more accurate measurements

    - **Full Speed Tests**: Comprehensive analysis with quality scoring

    - **Real-time Monitoring**: Server-Sent Events (SSE) for live progress
    tracking

    - **Historical Data**: Store and retrieve test results with statistics

    - **Comparative Analysis**: Compare results over time

    - **Server Selection**: Test against specific servers


    ## Authentication


    Most endpoints require the `Xerobi-Version` header:


    ```bash

    curl -H "Xerobi-Version: 2.0.0" \
      https://api.hixbe.com/speedtest/full
    ```


    **Exceptions**: The `/` (docs) and `/health` endpoints don't require this
    header.


    ## Rate Limits


    - **Basic endpoints** (ping, download, upload): 60 requests/minute

    - **Full/Advanced tests**: 10 requests/minute

    - **Results/Stats endpoints**: 120 requests/minute


    Rate limit information is included in response headers.


    ## Test Result Storage


    Results from these endpoints are automatically stored:

    - `/ping` - Basic latency tests

    - `/download` - Download speed tests

    - `/upload` - Upload speed tests

    - `/full` - Comprehensive tests

    - `/advanced` - Advanced multi-file tests


    Each stored result receives a unique ID for later retrieval.


    ## Quality Score Calculation


    The quality score (0-100) is calculated based on:

    - **Ping** (30%): < 20ms = excellent, < 50ms = good, < 100ms = fair

    - **Jitter** (20%): < 5ms = excellent, < 15ms = good, < 30ms = fair

    - **Download** (25%): Relative to expected speeds

    - **Upload** (20%): Relative to expected speeds

    - **Packet Loss** (5%): 0% = perfect, < 1% = excellent, < 5% = acceptable


    ## Server-Sent Events (SSE)


    The `/stream` endpoint provides real-time progress updates:


    ```javascript

    const eventSource = new EventSource('/speedtest/stream', {
      headers: { 'Xerobi-Version': '2.0.0' }
    });


    eventSource.addEventListener('ping', (e) => {
      const data = JSON.parse(e.data);
      console.log('Ping:', data.result, 'ms');
    });


    eventSource.addEventListener('finish', (e) => {
      const data = JSON.parse(e.data);
      console.log('Complete:', data.result);
      eventSource.close();
    });

    ```


    ## Best Practices


    1. **Use appropriate test types**: Use basic tests for quick checks,
    advanced tests for accuracy

    2. **Handle rate limits**: Implement exponential backoff for retries

    3. **Store results**: Use result IDs to track performance over time

    4. **Compare wisely**: Use `/comparison` and `/stats` for trend analysis

    5. **Real-time updates**: Use `/stream` for UI progress indicators

    6. **Server selection**: Use `/servers` to find optimal test servers


    ## Support


    - Website: https://hixbe.com

    - Documentation: https://docs.hixbe.com/speedtest

    - Status: https://status.hixbe.com
  version: 2.0.0
  contact:
    name: Xerobi Support
    url: https://hixbe.com
    email: support@xerobi.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.hixbe.com/speedtest
    description: Production server
security: []
tags:
  - name: Information
    description: API information, documentation, and health checks
  - name: Basic Metrics
    description: Individual speed test metrics (ping, jitter, download, upload)
  - name: Advanced Tests
    description: Comprehensive and multi-file speed tests for accuracy
  - name: Results & History
    description: Retrieve stored test results with filtering and statistics
  - name: Real-time
    description: Real-time test monitoring via Server-Sent Events (SSE)
  - name: Servers
    description: Test server management and selection
paths:
  /stream:
    get:
      tags:
        - Real-time
      summary: Real-time Test Stream
      description: >-
        Server-Sent Events (SSE) endpoint that streams real-time progress
        updates during a full speed test.


        **Event Types:**

        - `ping`: Ping test starting/completed

        - `jitter`: Jitter test completed

        - `download`: Download test starting/completed

        - `upload`: Upload test starting/completed

        - `finish`: Test completed with all results

        - `error`: Test failed with error details


        **Event Data:**

        - `status`: Test phase status (starting/completed)

        - `result`: Test result value

        - `progress`: Overall test progress (0-100%)


        **Implementation Example:**

        ```javascript

        const eventSource = new EventSource(
          'https://api.hixbe.com/speedtest/stream',
          { headers: { 'Xerobi-Version': '2.0.0' } }
        );


        eventSource.addEventListener('ping', (e) => {
          const data = JSON.parse(e.data);
          console.log('Ping:', data.result, 'ms');
          updateProgress(data.progress);
        });


        eventSource.addEventListener('finish', (e) => {
          const data = JSON.parse(e.data);
          console.log('Complete:', data.result);
          eventSource.close();
        });


        eventSource.addEventListener('error', (e) => {
          console.error('Error:', e.data);
          eventSource.close();
        });

        ```


        **Use Cases:**

        - Real-time UI updates

        - Progress bars

        - Live test monitoring

        - Interactive dashboards


        **Note**: Keep connection open until 'finish' or 'error' event received.
      operationId: streamTest
      parameters:
        - $ref: '#/components/parameters/HixbeVersion'
      responses:
        '200':
          description: Stream connection established
          content:
            text/event-stream:
              schema:
                type: object
                description: Server-Sent Events stream with test progress
                properties:
                  event:
                    type: string
                    enum:
                      - ping
                      - jitter
                      - download
                      - upload
                      - finish
                      - error
                  data:
                    type: string
                    description: JSON-encoded event data
              examples:
                pingStart:
                  summary: Ping test starting
                  value: |+
                    event: ping
                    data: {"status":"starting","progress":10}

                pingComplete:
                  summary: Ping test completed
                  value: |+
                    event: ping
                    data: {"result":25.5,"progress":20}

                downloadStart:
                  summary: Download test starting
                  value: |+
                    event: download
                    data: {"status":"starting","progress":40}

                finish:
                  summary: Test completed
                  value: >+
                    event: finish

                    data:
                    {"result":{"ping":25.5,"jitter":2.3,"download":95.42,"upload":48.75,"qualityScore":92},"progress":100}

                error:
                  summary: Test failed
                  value: |+
                    event: error
                    data: {"error":"Test timeout","progress":50}

        '400':
          $ref: '#/components/responses/MissingVersionHeader'
components:
  parameters:
    HixbeVersion:
      name: Xerobi-Version
      in: header
      description: API version header. Required for all endpoints except / and /health
      required: true
      schema:
        type: string
        pattern: ^\d+\.\d+\.\d+$
        example: 2.0.0
  responses:
    MissingVersionHeader:
      description: Missing Xerobi-Version header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        timestamp:
          type: string
          format: date-time
        error:
          type: object
          properties:
            code:
              type: string
              example: INVALID_REQUEST
            message:
              type: string
              example: Invalid request parameters
            details:
              type: object
              nullable: true

````

## Related topics

- [Xerobi Developer Documentation](https://docs.xerobi.com/index.md)
- [Jitter Test](https://docs.xerobi.com/speed-api/endpoint/jitter-test.md)
- [Xerobi SMS Gateway API Introduction](https://docs.xerobi.com/sms-api/introduction.md)
- [Xerobi Payment API Introduction](https://docs.xerobi.com/payment-api/introduction.md)
- [Webhooks](https://docs.xerobi.com/faq-guides/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.