SAsamsara
Idling

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.

<b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select Read Idling under the Fuel & Energy category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

get/idling/events

Request

  • Base URL
    https://api.samsara.com
  • Auth
    HTTP bearer

Query parameters

startTimestring 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.

endTimestring 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.

assetIdsstring[]

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

operatorIdsstring[]

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

ptoState'active' | 'inactive'

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

minAirTemperatureMillicelsiusinteger

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.

maxAirTemperatureMillicelsiusinteger

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.

excludeEventsWithUnknownAirTemperatureboolean

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

minDurationMillisecondsinteger

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.

maxDurationMillisecondsinteger

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.

tagIdsstring[]

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

parentTagIdsstring[]

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.

includeExternalIdsboolean

Optional boolean indicating whether to return external IDs on supported entities

afterstring

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.

limitinteger

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

Response

OK response.

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.