Register a real-time query
Registers a standing query for the real-time WebSocket stream and returns its registration_id. Use that id to connect to the stream at wss://ws.newsdata.io/ws/event and to manage the registration with /1/websocket/fetch and /1/websocket/delete. Available on plans with WebSocket access.
At least one of the following parameters is required: q, qInTitle, qInMeta, country, category, language, domain, domainurl, prioritydomain, image, video, full_content. Registering the exact same set of parameters again returns 409 with the existing registration_id. Each account can keep a limited number of active registrations at a time (set by your plan); requests beyond the limit return 429.
Registering consumes no API credits, but requires at least 1 API credit remaining. Each article later delivered over the WebSocket stream consumes 1 API credit per connected device.
Query parameters
Your API key. Alternatively send it in the X-ACCESS-KEY HTTP header. One of the two MUST be present.
Search articles by keywords or phrases (matches title, description, content, keywords, and URL). Supports AND / OR operators and quoted phrases. Maximum length depends on your plan (default 100 characters). Use only one of q, qInTitle, qInMeta.
Search articles by keywords in the title only. Maximum length depends on your plan (default 100 characters). Use only one of q, qInTitle, qInMeta.
Search articles by keywords in the title, description, keywords, and URL. Maximum length depends on your plan (default 100 characters). Use only one of q, qInTitle, qInMeta.
Filter by country. Comma-separated ISO 3166-1 alpha-2 country codes, up to your plan's filter limit (default 5). Cannot be combined with excludecountry.
Exclude countries. Comma-separated ISO country codes, up to your plan's filter limit (default 5). Cannot be combined with country.
Filter by category. Comma-separated category names, up to your plan's filter limit (default 5). Cannot be combined with excludecategory.
Exclude categories. Comma-separated category names, up to your plan's filter limit (default 5). Cannot be combined with category.
Filter by language. Comma-separated ISO 639-1 language codes, up to your plan's filter limit (default 5). Cannot be combined with excludelanguage.
Exclude languages. Comma-separated language codes, up to your plan's filter limit (default 5). Cannot be combined with language.
Filter by news source. Comma-separated source ids (the id value returned by /1/sources), up to your plan's filter limit (default 5). Cannot be combined with domainurl or excludedomain.
Filter by news source domain, e.g. bbc.com. Comma-separated, up to your plan's filter limit (default 5). Cannot be combined with domain or excludedomain.
Exclude news source domains, e.g. bbc.com. Comma-separated, up to your plan's filter limit (default 5). Cannot be combined with domain or domainurl.
Restrict results to a tier of news sources ranked by quality and popularity: top, medium, or low.
Display article dates in a specific timezone (IANA name, e.g. Asia/Kolkata). Defaults to UTC.
Set to 1 to return only articles that include an image, or 0 to return the image_url field as null.
Set to 1 to return only articles that include a video, or 0 to return the video_url field as null.
Set to 1 to return only articles that include full content, or 0 to return the content field as null. Available on plans with full-content access.
Set to 1 to exclude duplicate articles. Available for dates from 2024-07-24 onward.
Filter articles by sentiment. Available on Professional and Corporate plans, for dates from 2024-01-12 onward.
Minimum sentiment confidence (1-100) for the chosen sentiment. Requires the sentiment parameter.
Filter by AI-classified topic tags (e.g. politics,technology). Comma-separated, up to your plan's filter limit (default 5). Available on Professional and Corporate plans, for dates from 2024-01-12 onward.
Filter by AI-extracted geographic region. Join sub-regions with - to require them together (e.g. paris-france). Comma-separated, up to your plan's filter limit (default 5). Available on Corporate plans, for dates from 2024-01-29 onward.
Filter by AI-extracted organization names. Comma-separated, up to your plan's filter limit (default 5). Available on Corporate plans, for dates from 2024-05-24 onward.
Filter by article author / byline. Comma-separated, up to your plan's filter limit (default 5).
Filter by content type, e.g. news, blog, podcast. Comma-separated, up to your plan's filter limit (default 5). Available for dates from 2025-11-28 onward.
Comma-separated list of response fields to leave out of each article. article_id cannot be excluded.
Response
Query registered.