Skip to main content
Loading...

API docs by

Events

Adding events can help you quickly identify, categorize, and search for points of interest in your data. Each event is tied to a device and time span, and can contain metadata.

You can list events by devices, time ranges, and metadata.

Operations

List events

Request

Retrieve a list of events.

Use the query parameter to filter events on key/value criteria. The queryFields parameter can be used in combination with query to specify which fields to filter events by.

Syntax:

  • key:value: matches events with metadata that contains a key named key with a value of value; use double quotes if the value contains spaces or special characters
  • key:value1,value2: matches events with metadata that contains a key named key with a value of either value1 or value2
  • key:*: matches events where any metadata that contains a key named key
  • *:value: matches events where any metadata that contains value as a value
  • foo: matches events with metadata where any key or value string contains foo

Multiple qualifiers can be used in the same query string; this will filter events where metadata matches the intersection of the qualifiers (AND).

Examples:

  • key1:value1 key2:value2: matches metadata that contains both a key named key1 with its value value1 and another key named key2 with its value value2
  • key:"value with spaces": matches metadata with a key named key and its value value with spaces
  • key:value foo: matches metadata that contains both a key named key with its value value and any key or value that contains the text foo

Note: The start and end query arguments will find any events which intersect the query range (inclusive of start and end).

Security
ApiKey(Required scopes: events.list)
Query
startstring, (date-time)

Start of an inclusive time range

endstring, (date-time)

End of an inclusive time range

createdAfterstring, (date-time)

Return all events created after this date and time

updatedAfterstring, (date-time)

Return all events updated after this date and time

projectIdstring

Filter events by project

deviceIdstring

Filter events matching device ID

eventIdstring

Filter events by exact event ID

deviceNamestring

Name of device associated with the event

device.namestringdeprecated

Equivalent to deviceName, and ignored if deviceName is supplied

device.idstringdeprecated

Equivalent to deviceId, and ignored if deviceId is supplied

querystring

Event query string. Comprises a space-separated list of event queries, where the syntax of those queries is described above.

queryFieldsArray of strings

Which fields to query events by. Defaults to "metadata".

Items Enum:"metadata""properties"
sortBystring

field to sort response items by

Enum:"id""deviceId""deviceName""device.name""device.id""start""createdAt""updatedAt"
eventTypeIdstring

Filter events by their event type.

sortOrderstring

Sort order for the sortBy field

Enum:"asc""desc"
limitnumber, [ 0 .. 2000 ]

Maximum number of items to return

Default:2000
offsetinteger, >= 0

Number of items to skip before returning the results

Default:0
Python
from foxglove.client import Client
from datetime import datetime, timedelta

token = "<YOUR API TOKEN HERE>"
client = Client(token=token)

client.get_events(
    device_id=device_id,
    sort_by=sort_by,
    sort_order=sort_order,
    limit=limit,
    offset=offset,
    start=datetime.now() - timedelta(hours=3),
    end=datetime.now() - timedelta(hours=1),
    query="key:val"
)

Responses

A list of device events

Bodyapplication/json
Array [
idstringrequired

ID of the event

startstring, (date-time)required

Event start time (inclusive)

endstring, (date-time)required

Event end time (inclusive)

deviceobject(DeviceSummary)

ID and name of a device.

metadataobjectrequired

Any metadata associated with the event

createdAtstring, (date-time)required

When the event was created

updatedAtstring, (date-time)required

When the event was last updated

eventTypeIdstring

ID of the event type.

propertiesobject(CustomPropertyValues)

A key-value map of the custom properties associated with this event.

deviceIdstringdeprecated

ID of the device associated with the event.

deprecated: Use device.id instead.

]
Response
[
  {
    "id": "string",
    "start": "2019-08-24T14:15:22Z",
    "end": "2019-08-24T14:15:22Z",
    "deviceId": "string",
    "device": { … },
    "metadata": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "eventTypeId": "string",
    "properties": { … }
  }
]