SSE Stream

The SSE (Server-Sent Events) Stream endpoint delivers news articles in real time as they are published. Instead of polling the API repeatedly, open a single persistent connection and receive articles automatically.

What is SSE Stream?

SSE Stream is a real-time news delivery channel built on the Server-Sent Events standard. You open one HTTP connection and the server pushes new articles to you as they appear — no repeated requests needed.

Use cases:

• Live news feeds and dashboards
• Real-time monitoring for specific topics, entities, or sentiment
• Breaking news alerts
• Streaming pipelines for data processing

Benefits:

• Instant delivery — no polling delay
• Uses standard SSE protocol — works in any language
• Automatic reconnection with no data loss via Last-Event-ID
• All /everything filters supported — language, category, sentiment, entities, and more
• Field selection with fl parameter to reduce payload size

Endpoint

GET https://api.apitube.io/v1/news/stream

Authentication

Pass your API key in one of two ways:

• Header (recommended): X-API-Key: YOUR_API_KEY
• Query parameter: ?api_key=YOUR_API_KEY

Without a valid API key the server returns HTTP 401.

Quick Start

cURL

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en"

The -N flag disables buffering so events appear in real time.

JavaScript (Browser)

const es = new EventSource(
    'https://api.apitube.io/v1/news/stream?api_key=YOUR_API_KEY&language.code=en'
);

es.addEventListener('article', (e) => {
    const article = JSON.parse(e.data);
    console.log(`[${e.lastEventId}]`, article.title);
});

es.addEventListener('error', (e) => {
    if (e.data) {
        console.error('Server error:', JSON.parse(e.data));
    }
});

// To disconnect:
// es.close();

Node.js

import EventSource from 'eventsource';

const es = new EventSource(
    'https://api.apitube.io/v1/news/stream?language.code=en',
    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

es.addEventListener('article', (e) => {
    const article = JSON.parse(e.data);
    console.log(`[${e.lastEventId}]`, article.title);
});

es.addEventListener('error', (e) => {
    if (e.data) {
        console.error('Server error:', JSON.parse(e.data));
    }
});

TIP

The eventsource npm package supports custom headers, which makes it the recommended choice for Node.js.

Python

import requests

url = 'https://api.apitube.io/v1/news/stream'
headers = {'X-API-Key': 'YOUR_API_KEY'}
params = {'language.code': 'en'}

with requests.get(url, headers=headers, params=params, stream=True) as r:
    for line in r.iter_lines(decode_unicode=True):
        if line:
            print(line)

SSE Event Format

The stream uses standard SSE format with three event types:

article — New Article

event: article
id: 123456
data: {"id":123456,"title":"...","source":{...},...}

• event: article — event type
• id: — article ID (used for reconnection)
• data: — full article JSON in the same format as the /everything endpoint

error — Server Error

event: error
data: {"code":"ER0301","message":"Balance exhausted"}

Sent when an error occurs (e.g., balance exhausted). The connection closes after an error event.

Heartbeat

: heartbeat

An SSE comment sent every 30 seconds as a keep-alive signal. This is not a named event — it simply prevents the connection from timing out.

Filtering

All filters available on the /everything endpoint work with SSE Stream:

By language:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en"

By category:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?category=tech"

By source:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?source.domain=reuters.com"

Multiple filters:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en&category=tech&sentiment.overall.polarity=positive"

For the full list of available filters, see Parameters.

Field Selection

Use the fl parameter to receive only the fields you need, reducing payload size:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en&fl=id,title,source.domain"

The data: payload will contain only the specified fields.

Reconnection with Last-Event-ID

SSE has built-in reconnection support. If the connection drops, the client can resume from where it left off using the Last-Event-ID header:

1. Connect and receive articles — each has a unique id:
2. Connection drops (network issue, server restart, etc.)
3. Reconnect with the last received ID:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  -H "Last-Event-ID: 123456" \
  "https://api.apitube.io/v1/news/stream?language.code=en"

The server will immediately deliver any articles published after ID 123456, then continue streaming new ones.

TIP

The browser EventSource API handles reconnection and Last-Event-ID automatically. If the connection drops, the browser will reconnect and resume from the last received event — no extra code needed.

Parameters

Parameter	Description
api_key	API key (alternative to X-API-Key header)
fl	Field selection (e.g., id,title,source.domain)
All /everything filters	language.code, category, source.domain, sentiment.overall.polarity, title, entity.name, and more

Technical Details

Property	Value
Poll interval	Every 10 seconds
Heartbeat interval	Every 30 seconds
Articles per poll cycle	Up to 50
Billing	1 credit per delivered article
Reconnection	Via Last-Event-ID header
Response header	X-Accel-Buffering: no

Billing

Each article delivered through the stream costs 1 credit. Credits are deducted in real time as articles arrive — not when you open the connection.

How it works:

1. When you connect, the server checks your balance. If you have no credits and no paid balance, the connection is rejected with HTTP 402 and error code ER0176.
2. While the stream is active, 1 credit is deducted per article sent to you.
3. If your balance runs out mid-stream, the server sends an error event with code ER0301 ("Balance exhausted") and closes the connection.

Credit source priority:

• If you have available plan credits (points), they are used first.
• If plan credits are exhausted and you have a positive paid balance, the paid balance is used instead.

Response headers sent on connection provide your current billing state:

Header	Description
x-subscription-plan	Your current plan (free, basic, pro, enterprise)
x-points-remaining	Remaining plan credits
x-balance-remaining	Remaining paid balance (in cents)

TIP

The stream does not charge for heartbeats or the connection itself — only for actual articles delivered. If no articles match your filters, no credits are spent.

Error Handling

Insufficient Balance

If your account has no credits and no paid balance, the server rejects the connection with HTTP 402:

{
    "error": {
        "code": "ER0176",
        "message": "You have no points on your account"
    }
}

Top up your balance or wait for plan credits to renew before reconnecting.

Invalid or Missing API Key

Returns a standard HTTP 401 JSON error response (not SSE):

curl -N -H "X-API-Key: invalid" \
  "https://api.apitube.io/v1/news/stream"

{
    "error": {
        "code": 401,
        "message": "Unauthorized"
    }
}

Balance Exhausted

If your balance runs out during an active stream, the server sends an error event and closes the connection:

event: error
data: {"code":"ER0301","message":"Balance exhausted"}

Next Steps

• Learn about all available Parameters
• Explore common workflow examples
• Check Authentication options
• See HTTP Response Codes for error handling

Support

If you encounter issues:

1. Check the Technical FAQ
2. Verify your API key on apitube.io
3. Contact support through the APITube website