NewsData.io is introducing real-time news streaming via WebSocket, enabling you to receive live news updates instantly as they are published - without the need for repeated API polling.
Base URL
GETwss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY®istration_id=YOUR_REGISTRATION_ID
Overview
The NewsData.io WebSocket API provides a persistent, low-latency connection that streams news articles to your application in real time. Once connected, matching articles are pushed directly to your client as they become available - making it ideal for live dashboards, news tickers, alert systems, and real-time monitoring tools.
Resource Information
| Response Format | JSON |
| Requires Authentication | Yes |
| Rate Limited | Not applicable |
API Credit Usage
Every article delivered through the WebSocket stream consumes 1 API credit per article.
Credits are deducted in real time as articles are pushed to your connection. The faster news matches your query, the faster credits are consumed - plan your filters accordingly to avoid unexpected credit usage.
Important: Monitor Your Credit Usage
There is no rate limit on WebSocket streaming. If your query matches a large volume of news, articles can be delivered continuously and your API credits may be consumed very quickly - even potentially exhausting your available credits instantly. Create your query and filters carefully before starting the stream. Use specific keywords, categories, countries, domainurl, or other filters to control the volume of matching news.
Connection Limits
| Limit | Value |
|---|---|
| Max registered queries per account | 1 (Free), 5 (Basic), 10 (Professional & Corporate) |
| Max devices per registered query | 5 |
Credit usage per connection: Each connected device or client consumes 1 API credit for every article delivered. If the same article is delivered to multiple connected devices, each device consumes 1 credit for that article.
Example: If one article matches your query and is delivered to 3 connected devices, it consumes 3 API credits. If 100 articles are delivered to 3 devices, 300 API credits will be consumed.
Steps to Start Streaming
1. Register a Query
Endpoint
POSThttps://newsdata.io/api/1/websocket/register?apikey=YOUR_API_KEY
Register a query with your desired filters to create a persistent stream subscription. On success, you receive a unique Registered ID (registration_id) that identifies this query. Use this ID to connect devices, fetch query details, or delete the query later.
Required Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| apikey | String | Yes | Your NewsData.io API key. |
The Real-time streaming API registration endpoint supports the following parameters.
| Name | Required | Description | Default | Example |
|---|---|---|---|---|
Search & Content Filters | ||||
qInTitle | OPTIONAL | Search news articles for specific keywords or phrases present in the news titles only. The value must be URL-encoded and the maximum character limit permitted is 512 characters. Note: qInTitle can't be used with q or qInMeta parameter in the same query. | - | qInTitle=pizza |
qInMeta | OPTIONAL | Search news articles for specific keywords or phrases present in the news titles, URL, meta keywords and meta description only. The value must be URL-encoded and the maximum character limit permitted is 512 characters. Note: qInMeta can't be used with q or qInTitle parameter in the same query. | - | qInMeta=pizza |
q | OPTIONAL | Search news articles for specific keywords or phrases present in the news title, content, URL, meta keywords and meta description. The value must be URL-encoded and the maximum character limit permitted is 512 characters. | - | q=pizza |
category | OPTIONAL | Search the news articles for a specific category. Include up to 5 categories per query on Free and Basic plans. Professional and Corporate plans support up to 10 categories. | - | category=sports,top |
excludecategory | OPTIONAL | You can exclude specific categories to search for news articles. Exclude up to 5 categories per query on Free and Basic plans. Professional and Corporate plans support up to 10 categories. Note: You can use either the 'category' parameter to include specific categories or the 'excludecategory' parameter to exclude them, but not both simultaneously. | - | excludecategory=top |
datatype | OPTIONAL | Specifies the type of the article. Supported values: news, blog, multimedia, forum, pressrelease, review, research, opinion, analysis, podcast. Include up to 5 datatype per query on Free and Basic plans. Professional and Corporate plans support up to 10 datatype. | - | datatype=news,blog |
tag | OPTIONAL | Search the news articles for specific AI-classified tags. Include up to 10 tags per query. With Custom AI Tags (Corporate Yearly Plan only), you can request your own tag to classify articles based on your specific topic or tag | - | tag=food,tourism |
organization | OPTIONAL | Search the news articles related to specific organizations. Include up to 10 tags per query. (Available only Corporate users) | - | organization=uber,apple |
creator | OPTIONAL | Search by name of the article author or content creator. Include up to 5 creators per query on Free and Basic plans. Professional and Corporate plans support up to 10 creators. | - | creator=chintan haria creator=liz carolan,luca socci |
sentiment | OPTIONAL | Search the news articles based on the sentiment of the news article (positive, negative, neutral). | - | sentiment=positive |
Location, Language & Time Filters | ||||
country | OPTIONAL | Search news articles from specific countries. Include up to 5 countries per query on Free and Basic plans. Professional and Corporate plans support up to 10 countries. | - | country=au,jp |
excludecountry | OPTIONAL | Exclude news articles from specific countries. Include up to 5 countries per query on Free and Basic plans. Professional and Corporate plans support up to 10 countries. Note: You can use either the 'country' parameter to include specific countries or the 'excludecountry' parameter to exclude them, but not both simultaneously. | - | excludecountry=au,jp |
region | OPTIONAL | Search the news articles for specific geographical regions. The region could be a city, district, county, state, country, or continent. Include 5 regions per query, and it can be customized up to 10 regions per query. (Available only for Corporate users). | - | region=city1,city2 region=city1-state1-country1, city2-country2 region=state-country region=los angeles-california-usa region=new york,chicago |
language | OPTIONAL | Search the news articles for a specific language. Include up to 5 languages per query on Free and Basic plans. Professional and Corporate plans support up to 10 languages. | - | language=fr,en,ga |
excludelanguage | OPTIONAL | You can exclude specific languages to search for news articles. Exclude up to 5 languages per query on Free and Basic plans. Professional and Corporate plans support up to 10 languages. Note: You can use either the 'language' parameter to include specific languages or the 'excludelanguage' parameter to exclude them, but not both simultaneously. | - | excludelanguage=fr,en,ga |
Source, Quality & Intelligence Controls | ||||
domainurl | OPTIONAL | Search the news articles for specific domains or news sources. Include up to 5 domains per query on Free and Basic plans. Professional and Corporate plans support up to 10 domains. Note: If the domain is incorrect, It will give suggestions in the response | - | domainurl=nytimes.com, bbc.com,bbc.co.uk |
excludedomainurl | OPTIONAL | You can exclude specific domains or news sources to search the news articles. Exclude up to 5 domains per query on Free and Basic plans. Professional and Corporate plans support up to 10 domains. Note: If the domain is incorrect, It will give suggestions in the response | - | excludedomainurl=nytimes.com, bbc.com,bbc.co.uk |
prioritydomain | OPTIONAL | Search the news articles only from top news domains. We have categorized prioritydomain in 3 categories. Top: Fetches news articles from the top 10% of the news domains Medium: Fetches news articles from the top 30% of the news domains. It means it already includes all the news articles of 'top' priority. Low: Fetches news articles from the top 50% of the news domains. It means it already includes all the news articles of 'top' and 'medium' priorities. | - | prioritydomain=top prioritydomain=medium prioritydomain=low |
sentiment_score | OPTIONAL | Filters articles by sentiment score. Returns only articles with a sentiment score greater than or equal to the specified value. Note: Works only when the sentiment parameter is enabled. | - | sentiment_score=70 |
image | OPTIONAL | Search the news articles with featured image or without featured image. Use 1 for articles with featured image and 0 for articles without featured image. | - | image=1 image=0 |
video | OPTIONAL | Search the news articles with videos or without videos. Use 1 for articles with videos and 0 for articles without videos. | - | video=1 video=0 |
full_content | OPTIONAL | Search the news articles with full content or without full content. Use '1' for news articles which contain the full_content response object and '0' for news articles which don't contain full_content response object. | - | full_content=1 full_content=0 |
removeduplicate | OPTIONAL | The 'removeduplicate' parameter will allow users to filter out duplicate articles. Use 1 to remove duplicate articles. (Note: The overall 'removeduplicate' parameter functioning works on the basis of Newsdata.io's internal algorithm. It doesn't imply that the article which has a 'removeduplicate=1' parameter is actually a duplicate article.) | - | removeduplicate=1 |
Request Control & Response Handling | ||||
apikey | Required | You need to add your API Key while accessing the newsdata API. | - | - |
Plus at least one filter from the Minimum Required Filters listed below.
q, qinmeta, qintitle, category, country, language, domainurl, prioritydomain, image, video, or full_content is required to register a query
Example Response
{status: "success"results: {message: "Query registered successfully"registration_id: "e0a9d7ad4ac90fe9d449a184a5e1ef2f"}}Response Fields
| Parameter | Type | Description |
|---|---|---|
| status | string | success or error |
| results | object | Contains the registration response details |
| message | string | Human-readable confirmation |
| registration_id | string | Unique ID assigned to the registered query |
2. Fetch Data from Real-time Streaming API
Endpoint
Real-time Streaming API
GETwss://ws.newsdata.io/ws/event?apikey=YOUR_API_KEY®istration_id=YOUR_REGISTRATION_ID
Connect to websocket using its registration_id to start receiving real-time news updates. Once connected, matching articles are pushed directly to your client as they become available.
Required Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| apikey | String | Yes | Your NewsData.io API key. |
| registration_id | String | Yes | Unique ID of the registered query you want to connect to. |
Once the connection is established, your client will receive matching news articles through the real-time streaming api connection as they become available.
3. Fetch Registered Queries
Endpoint
GEThttps://newsdata.io/api/1/websocket/fetch?apikey=YOUR_API_KEY
Retrieves all registered queries you’ve created, including their filter configuration and current connection information. This endpoint is useful for auditing active streams, monitoring connected clients, or debugging query configurations.
Required Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| apikey | String | Yes | Your NewsData.io API key. |
Example Response
{status: "success"totalQueries: 1results: {queries: [0: {registration_id: "490c97e67a03dba85d0b305968f0c4f3"active_clients: 1query: {language: [0: "en"]}}]}}Response Fields
| Field | Type | Description |
|---|---|---|
| status | string | success or error |
| totalQueries | integer | Total number of registered queries |
| queries | array | List of registered queries |
| registration_id | string | Unique ID assigned to the registered query |
| active_clients | Integer | Total number of clients/devices currently connected |
| news_type | string | Indicates the NewsData.io endpoint used by the registered query |
| query | object | Full filter configuration of the query |
registration_id, active_clients, news_type, and query are returned within each object in the queries array.
4. Delete a Registered Query
Endpoint
DELETEhttps://newsdata.io/api/1/websocket/delete?apikey=YOUR_API_KEY
Permanently deletes a specific registered query from your account. Once deleted, any devices connected via that registration_id will lose their stream.
Required Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| apikey | string | Yes | Your NewsData.io API key. |
| registration_id | string | Yes | The registered query ID to delete |
Example Response
{status: "success"results: {message: "Registration deleted successfully"registration_id: "e0a9d7ad4ac90fe9d449a184a5e1ef2f"}}Response Fields
| Field | Type | Description |
|---|---|---|
| status | string | success or error |
| message | string | Confirmation or error details |
| registration_id | string | The ID of the deleted query |
See also
Real-Time Streaming API GuideWas this page helpful?