Listing Events

Get a list of Events, reverse ordered by timestamp. Use parameters to filter the list.


GET https://utilityapi.com/api/v2/events
# Get a list of all Events
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/events'
# Get all undelivered Events
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/events?is_delivered=false'
Parameter Format Description Example
is_delivered Boolean Filter by is_delivered state. is_delivered=false
after UID String List items after this Event uid. after=456abc

Returns a EventListing object containing a list of Event objects. If the number of results is over 1000, a next parameter will have the link to the next in the series of lists.

// Example result
{
    "events": [
        {"uid": "12837438", "type": ...},
        {"uid": "12837438", "type": ...},
        ...
    ],
    "next": null,
}

This is the object that contains the Event results for the request. We don't just return a straight list of results so that we can paginate results if needed. Currently, the maximum results per request is set at 1000.

Parameter Format Description Example
events List(Event) List of Event results. [{"uid": ...}, ...]
next URL or null If there are more results than the page limit, this is a link to the next set of results. "https://utilityapi.com/api/v2/events?after=234"
// Example EventListing
{
    "events": [...],
    "next": null,
}
Code Response Format Description
200 EventListing Successful request.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param - One of the query parameters was invalid. Check the error description for more info.
We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid or missing access_token. See our docs on Authentication for how to properly use your access_token.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).