Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Get events long poll endpoint

options
https://api.box.com/2.0
/events

Returns a list of real-time servers that can be used for long-polling updates to the event stream.

Long polling is the concept where a HTTP request is kept open until the server sends a response, then repeating the process over and over to receive updated responses.

Long polling the event stream can only be used for user events, not for enterprise events.

To use long polling, first use this endpoint to retrieve a list of long poll URLs. Next, make a long poll request to any of the provided URLs.

When an event occurs in monitored account a response with the value new_change will be sent. The response contains no other details as it only serves as a prompt to take further action such as sending a request to the events endpoint with the last known stream_position.

After the server sends this response it closes the connection. You must now repeat the long poll process to begin listening for events again.

If no events occur for a while and the connection times out you will receive a response with the value reconnect. When you receive this response you’ll make another call to this endpoint to restart the process.

If you receive no events in retry_timeout seconds then you will need to make another request to the real-time server (one of the URLs in the response for this endpoint). This might be necessary due to network errors.

Finally, if you receive a max_retries error when making a request to the real-time server, you should start over by making a call to this endpoint first.

Response

application/jsonReal-time servers

Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events.

application/jsonClient error

An unexpected client error.

options
Get events long poll endpoint
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
curl -i -X OPTIONS "https://api.box.com/2.0/events" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
TypeScript Gen
await client.events.getEventsWithLongPolling();
Python Gen
client.events.get_events_with_long_polling()
.NET Gen
await client.Events.GetEventsWithLongPollingAsync();
Python
events = client.events().generate_events_with_long_polling()
for event in events:
    print(f'Got {event.event_type} event')
Node
client.events.getEventStream(function(err, stream) {
  if (err) {
    // handle error
  }
  stream.on('data', function(event) {
    // handle the event
  });
});

Response Example

{
  "chunk_size": 1,
  "entries": [
    {
      "type": "realtime_server",
      "url": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all",
      "ttl": "10",
      "max_retries": "10",
      "retry_timeout": 610
    }
  ]
}