Events
The Event API streams a notification each time data in a curve changes. The path is relative
to the base URL https://data-forecasts.volue.com/api/v1/timeseries.
Listen to events
Section titled “Listen to events”GET /eventsThe response uses the HTML5 Server-Sent Events (SSE) format. The server streams events for as long as you keep the connection open.
Parameters
Section titled “Parameters”| Name | Type | Description |
|---|---|---|
id |
integer | Required. The curve ID to get events for. Repeat for more curves. |
start_time |
datetime | Only receive events after this time |
last-event-id |
string | Only receive events after this event |
Example request
Section titled “Example request”GET /api/v1/timeseries/events?id=1&id=2&id=3 HTTP/1.1Host: data-forecasts.volue.comAuthorization: Bearer <token>Example response
Section titled “Example response”HTTP/1.1 200 OKContent-Type: text/event-streamCache-Control: no-cache, no-store, max-age=0, must-revalidatePragma: no-cache
id: 2787d085-1c51-413c-90c3-2e5da7228bceevent: curve_eventdata: {"id": 1, "created": "2017-05-04T08:14:30.075Z", "operation": "modify", "tag": "01", "issue_date": "2020-06-24T08:10:00Z", "range": {"begin": "2020-06-24T10:00:00+02:00", "end": "2020-06-24T19:00:00+02:00"}}
id: 346d05a4-252a-4b45-819e-1f4e0791f97aevent: curve_eventdata: {"id": 2, "created": "2017-05-04T08:14:47.064Z", "operation": "modify", "range": {"begin": "2019-06-24T20:00:00+02:00", "end": "2019-06-24T22:00:00+02:00"}}
id: b9f29368-f271-4f58-b784-60ca676638c6event: curve_eventdata: {"id": 809, "created": "2026-11-03T11:17:33.407Z", "operation": "new_instance", "issue_date": "2026-11-03T11:15:00Z"}A new issue of an instance curve typically gives a new_instance event followed by a modify
event for the same issue_date.
Response fields
Section titled “Response fields”| Name | Type | Description |
|---|---|---|
id |
string | The event ID |
event |
string | The event type |
data.id |
integer | The ID of the curve that triggered the event |
data.created |
string | Time stamp of the event |
data.operation |
string | The operation on the curve: new_instance (an instance or tagged instance was created), modify (data was written to the curve, inserts and updates) or delete_instance (an instance was deleted) |
data.range |
object | Optional. The range of values that changed (begin, end). Not included for new_instance |
data.issue_date |
string | Optional. The issue that changed |
data.tag |
string | Optional. The tag that changed |
The data format may get new fields. Ignore fields you do not recognise.
Connections and reconnects
Section titled “Connections and reconnects”- Reconnect. Events use long-lived connections. We try to keep your connection open, but disconnects happen, and a connection can be closed after a few minutes. Implement reconnect logic if you listen over long periods. If the connection breaks at a consistent interval, check your network setup and the timeout settings of the library or tool you use.
- Resume. Send
Last-Event-IDwhen you reconnect to receive the events you missed. This recovers a few minutes of history, no more. After a longer disconnect, check the curves’modifiedtime to find what changed. - Heartbeats. When there are no events, the server sends a heartbeat about every 15
seconds to keep the connection alive through proxies and firewalls. Heartbeats are SSE
comment lines, for example
:Heartbeat at 2026-11-03T11:14:12.11Z. SSE clients ignore them. - Curves per connection. There is a limit to how many curves one connection can listen to. We recommend at most 20 curves per connection. For more, use several connections and combine the results.
When to use events
Section titled “When to use events”Events are designed for live dashboards and similar uses, where you follow a limited set of
curves you consider critical. They are not intended for listening to thousands of curves.
To track changes to many curves, search with GET /curves and the
modified_since parameter instead. See Best practice.