NewsData.io Real-Time Streaming API: A Beginner’s Guide

In today’s fast-changing world, information updates every second, and everyone wants information and replies within minutes. Whether a user wants information about the weather, the stock market, real-time news update and even replies to their chats and comments, nobody feels the need to wait hours for an update or reply.

This is where the Newsdata.io Streaming News API comes into frame.

Unlike a traditional API that requires you to repeatedly request to get new data and would make you refresh the page many times, a Streaming News API continuously delivers real-time news updates as they become available. Behind the scenes, this is made possible through WebSocket technology, which allows news updates to be sent instantly.

Do not get tense if terms like “Streaming API” or “WebSocket” sound technical. In this guide, we’ll explain everything in simple language and show how the NewsData.io Streaming News API works, and how you can start using it with tools like Postman.

I am text block. Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

What is the Streaming News API?

A Streaming News API is a service that allows the client and server to have real-time, updated communication with a persistent connection.

Think about how you normally check for updates. You open a website, refresh the page, and look for new information.

Traditional APIs work similarly. Your application asks for data, receives a response, and then asks again when it needs fresh information.

Request News
↓
Receive Response
↓
Request Again
↓
Receive Response
 

A Streaming News API works differently. Instead of repeatedly asking for updates, your application connects once and stays connected. Whenever new matching news becomes available, it is automatically delivered to your application.

Connect Once
↓

Stay Connected
↓

Receive Updates Automatically

This approach makes it possible to build applications that react to news as it happens.

How NewsData.io Real-Time Streaming Works

Step 1: Register a Query

To receive live news updates, you need to register a query with NewsData.io.

Think of a registered query as setting up your personalised news feed. You define what type of news you want to receive by adding filters and parameters. Once registered, the Real-Time Streaming API continuously looks for new articles that match your query and sends them to your connected clients.

Commonly Used Parameters

NewsData.io also supports additional parameters such as qinmeta, qintitle, domainurl, prioritydomain, sentiment, tag, region,and others for more advanced filtering.

You can explore all supported parameters and their usage in the Real-Time Streaming API documentation

Important: You must provide at least one filter parameter when registering a query. A query cannot be registered without a filter.

Registration Endpoint

To register a query, send a POST request to:
POST https://newsdata.io/api/1/websocket/register?apikey=YOUR_API_KEY

You can include your desired filters as request parameters.

Example: Register a Query

Suppose you want to receive real-time articles aboutArtificial Intelligencefrom theUnited States, in English

Your request can look like this:

POST https://newsdata.io/api/1/websocket/register?apikey=YOUR_API_KEY&q=artificial%20intelligence&country=us&language=en

Here:

• apikey authenticates your request.
• q=artificial intelligence tells NewsData.io to look for articles related to artificial intelligence.
• country=us limits results to news from the United States.
• language=en limits results to English-language articles.

You can combine multiple supported parameters to make your query more specific.

Example Response

If the query is successfully registered, NewsData.io returns a response containing a unique registration ID

{
"status": "success",
"registration_id": "your_registration_id"
}

The exact response fields may vary based on the API response.

The registration ID is important because it acts as the unique identifier for your registered query. You will use this ID in the next steps to connect your client to the real-time stream and manage the registered query.

Why Your Query Matters

Real-Time Streaming API sends articles as soon as they match your registered query. This means a broad query can potentially match a large number of articles and consume credits quickly.

For example, a query like:

q=news

may match a very large number of articles.

A more focused query such as:
q=artificial intelligence&country=us&language=en

can help you receive more relevant articles.

Create your queries carefully and use relevant filters to avoid consuming credits on articles you don’t need.

Once your query is registered and you have received theregistration ID, you are ready to connect a client and start receiving live news updates.

Step 2: Connect to the Streaming API

To connect to the real-time stream, you’ll need the following:

You obtained the registration_id in Step 1: Register a Query.

WebSocket Endpoint

Use the following WebSocket endpoint to connect to the stream:

wss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY&registration_id=YOUR_REGISTRATION_ID

Replace

• YOUR_API_KEY with your NewsData.io API key.
• YOUR_REGISTRATION_ID with the registration ID returned when you registered your query.

For example:

wss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY&registration_id=abc123

Important: The streaming endpoint uses wss://, which establishes a secure WebSocket connection.

How the Connection Works

Once the connection is established, NewsData.io starts listening for new articles that match your registered query.
or example, if your query is tracking Artificial Intelligence news from theUnited States in b>English, the Streaming API will continuously monitor incoming articles. Whenever a new article matches those filters, it will be sent to your client automatically.

This means you don’t have to refresh the page or repeatedly make API requests to check for updates. NewsData.io delivers the articles as soon as they become available.

Simple Process

Register Query

↓

Receive Registration ID

↓

Connect to Stream

↓

Stay Connected

↓

Receive Matching Articles

Why This Matters

The biggest advantage of the Streaming API is that it provides updates in real time. Once the connection is active, NewsData.io continuously sends matching articles whenever they are published.

This makes it ideal for applications such as live news dashboards, monitoring tools, breaking news alerts, and AI-powered systems that rely on fresh news data.

Step 3: View Registered Queries

After you are done with registering one or more queries,Newsdata.iowill allow you to check and view your active subscriptions.

Think of this as viewing a list of all the real-time news streams you have created. It helps you keep track of the queries that are currently active and receiving news updates.

This can be useful for:

• Tracking active streams – See which queries are currently registered and running.
• Reviewing filters – Check the keywords, categories, countries, or other filters used in each query.
• Monitoring subscriptions – Verify that the correct queries are active and receiving updates.

This feature is particularly helpful when you are working with multiple queries, as it allows you to quickly review and manage your active streaming subscriptions from one place.

Fetch Registered Queries

To retrieve your registered queries, send a GET request to:

GET https://newsdata.io/api/1/websocket/fetch?apikey=YOUR_API_KEY

Here:

• apikeyauthenticates your request.
• The endpoint returns information about the queries you have registered.
• The response can be used to review your active streaming subscriptions and their configured filters.

Example Response:

Step 4: Delete a Registered Query

After viewing all the queries that you have registered, there will be some queries that you will not be requiring anymore.

For example, you might have created a query for a specific event, campaign, or topic that you no longer want to track. In such cases, NewsData.io allows you to delete the registered query.

Removing unused queries helps keep your subscriptions organised and ensures that you’re only receiving updates that are relevant to you.

More importantly, it can help prevent unnecessary API credit consumption by stopping articles from being delivered for queries you no longer use.

Once a query is deleted, NewsData.io will stop monitoring it, and no further news updates will be sent for that registration ID.

Delete a Registered Query

To delete a registered query, send a DELETE request to:

DELETE https://newsdata.io/api/1/websocket/delete?apikey=YOUR_API_KEY&registration_id=YOUR_REGISTRATION_ID

The apikey parameter is used to authenticate your request.

You will also need to provide theregistration ID of the query you want to delete, as shown in the registered-query information from the previous step.

Example Response

After successfully deleting the query, the API returns a response confirming the operation.

The response can be used to verify that the selected registration has been removed successfully.

Note: Make sure you use the correct registration ID when deleting a query. Once deleted, the query will no longer be monitored and will stop delivering news updates.

How to Test the NewsData.io Streaming API Using Postman

If you’re new to APIs and WebSockets, don’t worry; you don’t need to write any code to manage your real-time streaming queries.

In fact, tools like Postman make the entire process much easier. Whether you’re registering a new query, viewing your existing queries, or deleting an old one, you can do everything directly from Postman using simple HTTP requests.

To get started quickly, you can use the official NewsData.io Postman Collection. The collection provides ready-to-use API requests that you can import into Postman and configure with your API key.

Before you get started, there are three important things to keep in mind.

1. All Parameters Go in the Query String

For the NewsData.io Real-Time Streaming API, all parameters should be passed through the query string. In Postman, you can add these parameters using the Params tab.

This applies to all query management endpoints, including:

• Registering a query
• Fetching your registered queries
• Deleting a registered query

2. Include Your API Key

Every request must include your NewsData.io API key. The API key is passed as a query parameter called apikey.  Without a valid API key, the request will not be authenticated, and the operation will automatically fail.

3. Use the Correct HTTP Method

Each endpoint performs a different action, so it’s important to select the correct          

• HTTP method when making a request.
• POST is used to register a new query.
• GET is used to view existing registered queries.
• DELETE is used to remove a registered query.

Using the wrong HTTP method is one of the most common reasons requests fail, so it’s always worth double-checking before sending your request.

Once you understand these three basics, managing real-time streaming queries becomes much simpler, even for users with little or no development experience.

1. REGISTER a query

Registering means “remember this filter for me”. The server stores the query and returns a registration_id, which you can use later to manage and stream the registered query.

Method: POST

URL: https://newsdata.io/api/1/websocket/register

Params tab:

In Postman, open the Params tab and add the following parameters:

Postman will automatically build the complete URL:

https://newsdata.io/api/1/websocket/register?apikey=YOUR_API_KEY&q=pizza&language=en<

Step-by-Step in Postman

1. Click New → HTTP Request.
2. Change the method from GETtoPOST.
3. Enter the following URL:
   https://newsdata.io/api/1/websocket/register
4. Open the Params tab and add the supported parameters you want to use based on your search.
5. Click Send.

Example Response

A successful request returns a response similar to:

{
"status": "success",
"results": {
< "message": "registered",
"registration_id": "abc123def456"
}
}

Copy that registration_id somewhere safe. It is how you refer to this query from now on.
You can use any of the supported news filters, including: q, qInTitle, qInMeta, country, category, language, domain, timezone, tag, sentiment, image, video, full_content, removeduplicate, and so on.

For a filter that takes several values, separate them with commas and no spaces:
country: us,gb,in
category: business,technology

Note that some pairs are mutually exclusive; you cannot send both country and excludeCountry, or both q and qInTitle, in the same registration.

Register a Query in Postman

The GIF below demonstrates the complete process of registering a query in Postman, from selecting the POST method and adding your search parameters to sending the request and receiving the registration_id.

This gives you a quick visual guide to follow along with the steps above.

2. Fetch news using the registered query

Once your query is successfully registered, you receive a registration_id. You can use this ID to connect to the NewsData.io Streaming API and start receiving news articles that match your registered filters.

For example, if your registration returned:

registration_id = abc123def456

you can use it with your API key to connect to the WebSocket endpoint.

WebSocket URL:

wss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY&registration_id=abc123def456

Replace:

• YOUR_API_KEY with your NewsData.io API key.
• abc123def456 with the registration_id returned when you registered your query.

Step-by-Step in Postman

1. Open Postman.
2. Click New → WebSocket.
3. Enter the WebSocket URL:

wss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY&registration_id=YOUR_REGISTRATION_ID

1. Replace the API key and registration ID with your actual values.
2. Click Connect.
3. Keep the WebSocket connection open.
4. When a new article matches your registered query, NewsData.io will send the article through the connection.

The stream will deliver matching news articles as they become available.

3. FETCH your registered queries

This endpoint is used to fetch all currently registered NewsData.io Real-time streaming API queries for an account.

Method:GET

URL:https://newsdata.io/api/1/websocket/fetch

Params tab:

Full URL:https://newsdata.io/api/1/websocket/fetch?apikey=YOUR_API_KEY

The response looks like this:
{
"status": "success",
"totalQueries": 1,
"results": {
"queries":[
{
"registration_id": "bf51c325aae34830800cc30a31608e4c",
"active_clients": 0,
"last_used": null,
"news_type": "latest",
"query": {
"language": [
"en"
],
"q": "pizza"
}
}
]
}
}

What the response tells you

For each registered query, the response includes:

• registration_id- unique ID of the registered WebSocket query.
• active_clients- number of currently connected clients streaming that query.
• last_used – when the query was last used.
• news_type – e.g. latest.
• query – the filters registered for the query, such as:
  • >q
  • language
  • and potentially other query filters.

For your example, there is one registered query, with registration ID:
bf51c325aae34830800cc30a31608e4c

It is currently being used by 1 active client, and its filters include Pizza and English (en)

4. DELETE a query

When you no longer want a query, remove it with its registration_id.

Method: DELETE
URL: https://newsdata.io/api/1/websocket/delete?apikey=YOUR_API_KEY

Params tab:

Full URL: https://newsdata.io/api/1/websocket/delete?apikey=YOUR_API_KEY&registration_id=YOUR_REGISTRATION_ID 

Step by step in Postman:

1. 1. Set the method to DELETE.
   2. Enter:
      DELETE https://newsdata.io/api/1/websocket/delete?apikey=YOUR_API_KEY&registration_id=YOUR_REGISTRATION_ID
   3. Open Params.
   4. Add:

• apikey → your API key

• registration_id → the registration ID to add

1. Click Send.

 The response looks like this:
{
"status": "success",
"results": {
"message": "Registration deleted successfully",
"registration_id": "bf51c325aae34830800cc30a31608e4c"
}
}<b></b>

After successful deletion, that registration no longer exists, so clients cannot continue streaming using that registration ID.

Understanding API Credit Usage

Before you start using the Streaming News API, it’s important to understand how API credits work. If you’ve used a regular API before, you may already know that credits are usually consumed when you make a request. The Streaming API works a little differently.

With the NewsData.io Streaming API, credits are consumed when news articles are delivered through the stream based on your registered query. In simple terms, credits are used when you receive matching articles, not when you establish the connection.

For example, if one article is sent to one device, one API credit is used. If the same article is sent to multiple devices, a credit is used for each device that receives it.

To make the most of your credits, use specific filters and track only the topics you’re interested in. This helps you receive more relevant news while avoiding unnecessary credit usage.

Common Response Codes You May Encounter

While using the NewsData.io Streaming API, you may come across some common response codes. Here’s what they mean and how to resolve them.

401 / 403 – Authentication Error

This usually means your API key is incorrect, missing, or your current plan does not include access to the Real-Time Streaming API.

How to fix it: Check that you have entered the correct API key. Even an extra space copied by mistake can cause this error.

409 – Query Already Exists

This response appears when you try to register a query that has already been registered.

How to fix it: This isn’t really an error. The response will include the existing registration_id, which you can simply reuse instead of creating a new query.

404 – Query Not Found

This error can occur when trying to delete a query using a registration ID that doesn’t exist.

How to fix: Make sure the registration_id is correct and that the query hasn’t already been deleted.

429 – Too Many Requests

This response means too many requests have been sent within a short period of time.

How to fix it: Wait a few moments and try again later.

Conclusion

The NewsData.io Real-Time Streaming API makes it easier to receive news updates as they happen without repeatedly sending requests for new data. By using WebSockets, you can maintain a persistent connection and automatically receive articles that match your registered query.

As we covered in this guide, the basic process is simple: register a query, connect to the WebSocket stream, manage your registered queries, and receive matching news in real time. Tools like Postman can also help you test and manage your queries without writing code.

When setting up your streaming queries, remember to use relevant filters and keep track of your registered queries and API credit usage. With the right configuration, you can use the Streaming API to build applications such as live news dashboards, monitoring systems, breaking-news alerts, and other real-time news solutions.

Ready to get started? Register your query, connect to the stream, and start receiving real-time news with NewsData.io.