---
title: "Register a real-time query"
method: POST
path: "/1/websocket/register"
tags: ["Websocket"]
---

# Register a real-time query

`POST /1/websocket/register`

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

- `apikey` string
- `q` string
- `qInTitle` string
- `qInMeta` string
- `country` string[]
- `excludecountry` string[]
- `category` string[]
- `excludecategory` string[]
- `language` string[]
- `excludelanguage` string[]
- `domain` string[]
- `domainurl` string[]
- `excludedomain` string[]
- `prioritydomain` 'top' | 'medium' | 'low'
- `timezone` string
- `image` '0' | '1'
- `video` '0' | '1'
- `full_content` '0' | '1'
- `removeduplicate` '0' | '1'
- `sentiment` 'positive' | 'neutral' | 'negative'
- `sentiment_score` number
- `tag` string[]
- `region` string[]
- `organization` string[]
- `creator` string[]
- `datatype` string[]
- `excludefield` string[]

## Response `200`

Query registered.

- WebsocketRegisterEnvelope — Successful WebSocket query registration.
  - `status` 'success', required
  - `results` object, required
    - `message` string, required — Human-readable confirmation.
    - `registration_id` string, required — Identifier of the registered query (32 characters). Use it to connect to the WebSocket stream and to delete the registration.

## Other responses

- `400` — Invalid request — e.g. a required parameter is missing or the search query is malformed.
- `401` — Missing or invalid API key, or the request is not allowed for this key.
- `403` — Your plan does not include access to this endpoint or parameter.
- `409` — An identical query is already registered for this API key. `results.registration_id` carries the id of the existing registration.
- `422` — A parameter value is not supported — e.g. an unknown filter value, too many values, an invalid date, or two incompatible filters used together.
- `429` — Too many requests in a short period, rate limit exceeded, or API credits exhausted.
- `500` — Unexpected server error. Please try again later.
- `503` — The endpoint is temporarily unavailable due to maintenance.

## Changes

- **2026-08-20** `ece1fd088c73` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/newsdata/apis/newsdata-io-api/changes/1/websocket/register/post.md)

---

[API](https://skmtc.dev/newsdata/apis/newsdata-io-api.md) · [All operations](https://skmtc.dev/newsdata/apis/newsdata-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/newsdata/newsdata-io-api/revisions/ece1fd088c73/schema)