Get idling events.

Get idling events for the requested time duration.

Note: The data from this endpoint comes from the new Advanced Idling Report, which provides additional data fields for each idling event such as air temperature, geofence, PTO state and minimum idle time. This endpoint includes data from January 1, 2024. If you require additional historical data, you can access it via the vehicle idling reports API.

Rate limit: 5 requests/sec (learn more about rate limits here).

To use this endpoint, select Read Idling under the Fuel & Energy category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

GET /idling/events

Get idling events.

cURL

curl --request GET \
  --url https://api.samsara.com/idling/events \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "asset": {
        "id": 1234567890,
        "externalIds": {}
      },
      "durationMilliseconds": 860000,
      "eventUuid": "1234567890",
      "fuelConsumedMilliliters": 2500,
      "fuelCost": {
        "amount": "640.2",
        "currency": "usd"
      },
      "gaseousFuelConsumedGrams": 2500,
      "gaseousFuelCost": {
        "amount": "640.2",
        "currency": "usd"
      },
      "ptoState": "inactive",
      "startTime": "2019-06-13T17:08:25Z",
      "address": {
        "id": "1234567890",
        "addressTypes": [
          "yard",
          "industrialSite"
        ],
        "externalIds": {}
      },
      "airTemperatureMillicelsius": 25000,
      "latitude": 37.7749,
      "longitude": -122.4194,
      "operator": {
        "id": 1234567890,
        "externalIds": {}
      }
    }
  ],
  "pagination": {
    "endCursor": "MjkY",
    "hasNextPage": true
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

startTime · string · required

The start of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-11T19:00:00Z, 2015-09-12T14:00:00-04:00). Returns events that begin at or after this timestamp.

endTime · string · required

The end of the time range for filtering idling events in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:00:00Z, 2015-09-15T14:00:00-04:00). Returns events that begin before this timestamp.

assetIds · string[]

A filter on the data based on this comma-separated list of asset IDs. Asset IDs only include vehicle IDs at this time.

operatorIds · string[]

A filter on the data based on this comma-separated list of operator IDs. Operator IDs only include driver IDs at this time.

ptoState · enum<string>

A filter on the data on this PTO (Power Take-Off) state. If no specific state is provided, data including any state will be included. Valid values: active, inactive

Available options: active, inactive

minAirTemperatureMillicelsius · integer

A filter on the data based on the minimum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.

Required range: -20000 <= x <= 50000

maxAirTemperatureMillicelsius · integer

A filter on the data based on the maximum value of air temperature in millicelsius. The acceptable range for this value is between -20,000 and 50,000 millicelsius.

Required range: -20000 <= x <= 50000

excludeEventsWithUnknownAirTemperature · boolean · default: false

A filter on the data based on unknown air temperature value.

minDurationMilliseconds · integer

A filter on the data based on the minimum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.

Required range: 120000 <= x <= 86400000

maxDurationMilliseconds · integer

A filter on the data based on the maximum value of Idling duration in milliseconds. The acceptable range for this value is between 2 minutes and 24 hours.

Required range: 120000 <= x <= 86400000

tagIds · string[]

A filter on the data based on this comma-separated list of tag IDs. Tag IDs only include vehicle IDs at this time.

parentTagIds · string[]

A filter on the data based on this comma-separated list of parent tag IDs. Parent tag IDs only include vehicle IDs at this time.

includeExternalIds · boolean

Optional boolean indicating whether to return external IDs on supported entities

after · string

If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.

limit · integer · default: 200

The limit for how many objects will be in the response. Default and max for this value is 200 objects.

Required range: 1 <= x <= 200

Response

200

application/json

OK response.

data · object[] · required

List of idling event objects.

Show child attributes

pagination · object · required

Pagination parameters.

Show child attributes