events

Description

The /events endpoint enables retrieval of a user's event records. This includes carbohydrate intake, insulin doses, exercise, and health events that are entered in the receiver interface or through the mobile app. Event Mobile App Screen

Resource

GET /v3/users/self/events

Authorization

OAuth 2.0 bearer token; see the Authentication section for details on this workflow.

Notes

The unit enumerations vary between endpoints. For events, the values are as follows:

  • unknown
  • grams
  • mg/dL
  • minutes
  • units

For the systemTime and displayTime response fields, records sourced from mobile apps (with displayDevice of “iOS” or “android”) will have UTC offsets; records sourced from receivers (with displayDevice of “receiver”) will not have UTC offsets.

Dexcom ONE does not support the /events endpoint and will return an empty array.

SecurityBearerAuth
Request
query Parameters
startDate
required
string <date-time>

Beginning of the time window.

Example: startDate=2023-01-01T09:12:35
endDate
required
string <date-time>

End of the time window.

Example: endDate=2023-01-01T09:12:35
Responses
200

Ok

Response Schema: application/json
recordType
required
string

The type of records that will be returned in this response. Example: “event”

recordVersion
required
string

The version of records that will be returned in this response. Example: “3.0”

userId
required
string

This ID is unique on a per-Dexcom account, per-client basis, and will thus not be the same for a user across clients (even if the clients are owned by the same developer).

required
Array of objects (com.dexcom.partner.api.models.proto.v3.event.Event)

Array of events. The size of the array will be zero if there are no events. Example: events[]

Array
systemTime
required
string <date-time>

The recorded system time of the alerts/egv/calibration/event. This is the ISO 8601 time according to the system clock at which observation was made (UTC). Records sourced from mobile apps (with displayDevice of “iOS” or “android”) will have UTC offsets; records sourced from receivers (with displayDevice of “receiver”) will not have UTC offsets.

displayTime
required
string <date-time>

The recorded display time of the alerts/egv/calibration/event. This is the ISO 8601 time displayed on the receiving device when the observation was made (local). Records sourced from mobile apps (with displayDevice of “iOS” or “android”) will have UTC offsets; records sourced from receivers (with displayDevice of “receiver”) will not have UTC offsets. Maps to EventDisplayTime

recordId
required
string

A unique ID for the event record.

eventStatus
required
string

Describes the status of the record being posted from the health database. It describes if it is a brand-new entry, or if the record has been modified, or if the record has been deleted by the user.

Enum: "created" "updated" "deleted"
eventType
required
string

Name of the event.

Enum: "unknown" "insulin" "carbs" "exercise" "health" "bloodGlucose" "notes"
eventSubType
string or null

Additional event description corresponding to eventType field.

  • for eventType "carbs": null
  • for eventType "notes": null
  • For eventType "insulin":
  • "fastActing","longActing"
  • For eventType "exercise": ("light","medium","heavy")
  • For eventType "health": ("illness","stress","highSymptoms","lowSymptoms","cycle","alcohol")
  • For eventType "bloodGlucose": null
Enum: "unknown" null "fastActing" "longActing" "light" "medium" "heavy" "illness" "stress" "highSymptoms" "lowSymptoms" "cycle" "alcohol"
value
required
string

Value of input

unit
string or null

Unit of measurement for the value field

  • for eventType "carbs": "grams"
  • for eventType "notes" : null
  • for eventType "insulin": "units" Please see Notes section above for more information on enumeration values. Enum: "unknown" "grams" "mg/dL" "minutes" "units"
transmitterId
required
string

A hashed and encrypted version of the unique ID of the transmitter. This may be used to determine uniqueness of transmitter or associate multiple records with the same transmitter, but it cannot be matched to the real transmitter ID.

transmitterGeneration
required
string

The generation of transmitter that was associated with this upload.

Enum: "unknown" "g4" "g5" "g6" "g6+" "dexcomPro" "g7"
displayDevice
required
string

The generation of transmitter that was associated with this upload. Enum: "unknown""receiver" "iOS" "android"

get/v3/users/self/events
Request samples
curl -i -X GET \
  'https://api.dexcom.com/v3/users/self/events?startDate=2023-01-01T09%3A12%3A35&endDate=2023-01-01T09%3A12%3A35' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "recordType": "events",
  • "recordVersion": "3.0",
  • "userId": "5b329ebcfbf2f0ba7e49d4c5eb57775468f5ee657ac16fcde07e1fd08197b4c7",
  • "records": [
    • {
      • "recordId": "763923b7-5424-451e-b37d-fd8ff635b308",
      • "systemTime": "2022-02-06T09:12:35+00:00",
      • "displayTime": "2022-02-06T01:12:35-08:00",
      • "eventStatus": "created",
      • "eventType": "insulin",
      • "eventSubType": "longActing",
      • "value": 400,
      • "unit": "units",
      • "transmitterId": "d55d01d0341ed0ba2cd99b322e8c5b609254f47d10c7cd12b99b4922effeba44",
      • "transmitterGeneration": "g6",
      • "displayDevice": "android"
      }
    ]
}