Realtime updates

Realtime updates allow you to receive notifications when lists or items are created, updated, or deleted. This can be useful when building collaborative applications, chat applications, or any other application which requires real-time data.

Realtime updates can be enabled or disabled for each list. If a list has realtime capabilities enabled, then you can receive updates for that list and any items within it. You can enable realtime capabilities for a list by setting the realtime field to true.

To receive realtime updates, you need to create a websocket connection to the following URL:

wss://realtime.jsonpad.io

The websocket connection is secured using TLS, so you need to connect to it using the wss protocol. You can connect using the native WebSocket API or using a library like Socket.IO.

You need to authenticate using a token, included in the x-api-token header. See Token Permissions for help with setting up a token.

You may prefer to use the Realtime SDK since it handles all of the internal logic for you. See Using the SDKs for more information.

When you connect to the websocket, you can specify which types of events you want to receive, and optionally which lists and/or items you want to receive updates for. Use the following parameters:

eventTypesstring
A comma-separated list of event types.
The following event types are available:
- 'list-created': A list was created
- 'list-updated': A list was updated
- 'list-deleted': A list was deleted
- 'item-created': An item was created
- 'item-updated': An item was updated
- 'item-restored': An item was restored to a previous state
- 'item-deleted': An item was deleted
listIdsstringA comma-separated list of List ids or path names.
itemIdsstringA comma-separated list of Item ids or alias values. Alias values can't be used while one of your alias indexes is being built: the connection is refused with INDEX_BUILDING, and the JS realtime SDK retries it.

Here's an example:

wss://realtime.jsonpad.io?eventTypes=list-updated,item-created,item-updated&itemIds=dd7383c8-238f-4d70-bf1a-85c79f63e51b

Note that if you don't specify any listIds or itemIds, you will receive updates for all lists and/or items. You can also use * to denote "all lists" or "all items".

When a realtime event occurs, you will receive a message with the following data:

{listId: "dd7383c8-238f-4d70-bf1a-85c79f63e51b"
itemId: "94edbcd9-8e5a-4b75-b17e-4a2be1ca626b"
model: null
}

required
listIdstringThe id of the list that was created / updated / deleted, or the id of the list which contains the item that was created / updated / deleted.
optional
itemIdstringThe id of the Item that was created / updated / deleted (only if this is an item event).
required
modelobjectA copy of the list or item that was created / updated / deleted.

Item data will generally be included in the model field for item events.

However, for performance reasons there is a maximum size limit for realtime events. This means that if an item's data is relatively large (greater than ~50KB), the data will not be included. In rare cases where a list or item is still too large to send (for example, a list with a very large schema), model will be null.

In this case, you can still use the realtime API to receive realtime events when an item changes, but you will need to manually re-fetch the item with its data attached via the API or SDK.

Connection limits

Each plan limits how many realtime connections one account can hold open at the same time. The limit covers connections made with any of your tokens, and every browser tab or device running your application holds its own connection — so in practice it caps how many of your users can receive updates at once. The number for each plan is on the pricing page, and your own is returned as plan.maxRealtimeConnections by GET /tokens/self.

Realtime messages themselves are not metered, and they don't count against your monthly request allowance. See limits and quotas.

A connection beyond the limit is refused during the handshake, before it is established. Socket.IO clients receive this as a connect_error, carrying data like this:

{name: "REALTIME_CONNECTION_LIMIT_EXCEEDED"
code: 10015
message: "Realtime connection limit exceeded (max: 1). Close another connection or upgrade your plan at https..."
max: 1
retryAfter: 45
}

retryAfter is how many seconds to wait before trying again. A connection that drops without closing cleanly — a device going offline, say — keeps its slot until the server notices it has gone, which takes up to that long. A client that reconnects immediately can therefore be refused for a limit it is no longer over. The Realtime SDK handles this for you, by retrying with a backoff.

Connections refused for any other reason, such as an invalid token or no event types, arrive the same way, carrying the name, code and message of the error. See errors.

Moving to a smaller plan doesn't close connections you already have open. The new limit applies to connections made after the change.

Token changes

A realtime connection is authenticated once, when it is established. The token's permissions are checked as they were at that moment, for as long as the connection stays open.

This means that regenerating a token's value, deactivating it, changing its permissions or deleting it doesn't close connections which are already open using that token. They keep receiving updates until they disconnect. When they try to reconnect, the token is checked again as it is at that point, so a regenerated value, or a deactivated or deleted token, will be refused.

If a token has been leaked, regenerate it from the dashboard, then restart or reconnect any of your own clients which use it. A connection opened with the leaked value will stop receiving updates once it disconnects.

2026-09-13