openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Idling API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Idling
paths:
  /fleet/reports/vehicle/idling:
    get:
      description: "Get all vehicle idling reports for the requested time duration.\n\n <b>Rate limit:</b> 25 requests/sec (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Read Fuel & Energy** 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>\n \n\n **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."
      operationId: getVehicleIdlingReports
      parameters:
      - description: ' 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.'
        in: query
        name: after
        schema:
          type: string
      - description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
        in: query
        name: limit
        schema:
          default: 512
          maximum: 512
          minimum: 1
          type: integer
      - description: ' A start time in RFC 3339 format. Defaults to now if not provided. Millisecond precision and timezones are supported. Note that the most recent 72 hours of data may still be processing and is subject to change and latency, so it is not recommended to request data for the most recent 72 hours. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: ' An end time in RFC 3339 format. Defaults to now if not provided. Millisecond precision and timezones are supported. Note that the most recent 72 hours of data may still be processing and is subject to change and latency, so it is not recommended to request data for the most recent 72 hours. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: endTime
        required: true
        schema:
          type: string
      - description: ' A filter on the data based on this comma-separated list of vehicle IDs and externalIds. Example: `vehicleIds=1234,5678,samsara.vin:1HGBH41JXMN109186`'
        in: query
        name: vehicleIds
        schema:
          type: string
      - description: ' A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
        in: query
        name: tagIds
        schema:
          type: string
      - description: ' A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
        in: query
        name: parentTagIds
        schema:
          type: string
      - description: A filter on the data based on power take-off being active or inactive.
        in: query
        name: isPtoActive
        schema:
          type: boolean
      - description: A filter on the data based on a minimum idling duration.
        in: query
        name: minIdlingDurationMinutes
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsResponseBody'
          description: OK response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsUnauthorizedErrorResponseBody'
          description: Unauthorized response.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsNotFoundErrorResponseBody'
          description: Not Found response.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsMethodNotAllowedErrorResponseBody'
          description: Method Not Allowed response.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsTooManyRequestsErrorResponseBody'
          description: Too Many Requests response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsInternalServerErrorResponseBody'
          description: Internal Server Error response.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsNotImplementedErrorResponseBody'
          description: Not Implemented response.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsBadGatewayErrorResponseBody'
          description: Bad Gateway response.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsServiceUnavailableErrorResponseBody'
          description: Service Unavailable response.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsGatewayTimeoutErrorResponseBody'
          description: Gateway Timeout response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdlingReportsGetVehicleIdlingReportsBadRequestErrorResponseBody'
          description: Bad Request response.
      summary: Get Vehicle Idling Reports.
      tags:
      - Idling
components:
  schemas:
    IdlingReportsGetVehicleIdlingReportsBadGatewayErrorResponseBody:
      description: Bad Gateway
      properties:
        message:
          description: Message of error
          example: 'rpc error: code = Unknown desc = connection refused'
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportEventAddressResponseBody:
      description: Address where the idling event took place.
      properties:
        formatted:
          description: The formatted address of the idling location.
          example: 123 Main Street Atlanta, GA 30307
          type: string
        latitude:
          description: The latitude of the idling location.
          example: 34.654567
          format: double
          type: number
        longitude:
          description: The longitude of the idling location.
          example: 34.654567
          format: double
          type: number
      required:
      - formatted
      - latitude
      - longitude
      type: object
    IdlingReportsGetVehicleIdlingReportsBadRequestErrorResponseBody:
      description: Bad Request parameters
      properties:
        message:
          description: Message of error
          example: Invalid value for parameter.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportEventResponseBody:
      description: A summary of the idling event.
      properties:
        address:
          $ref: '#/components/schemas/IdlingReportEventAddressResponseBody'
        durationMs:
          description: The duration of this idling event in milliseconds.
          example: 860000
          format: int64
          type: integer
        endTime:
          description: The end time of this idling event in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          type: string
        fuelConsumptionMl:
          description: The amount of fuel consumed in milliliters during this idling event.
          example: 2500
          format: double
          type: number
        isPtoActive:
          description: Whether or not power take-off was active during this idling event.
          example: false
          type: boolean
        startTime:
          description: The start time of this idling event in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          type: string
        vehicle:
          $ref: '#/components/schemas/GoaVehicleTinyResponseResponseBody'
      required:
      - address
      - durationMs
      - endTime
      - fuelConsumptionMl
      - isPtoActive
      - startTime
      - vehicle
      type: object
    IdlingReportsGetVehicleIdlingReportsResponseBody:
      properties:
        data:
          description: Multiple idling events.
          items:
            $ref: '#/components/schemas/IdlingReportEventResponseBody'
          type: array
        pagination:
          $ref: '#/components/schemas/GoaPaginationResponseResponseBody'
        requestEndTime:
          description: The requested end time in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          type: string
        requestStartTime:
          description: The requested start time in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          type: string
      required:
      - data
      - pagination
      - requestEndTime
      - requestStartTime
      type: object
    IdlingReportsGetVehicleIdlingReportsTooManyRequestsErrorResponseBody:
      description: Too many requests
      properties:
        message:
          description: Message of error
          example: Exceeded rate limit.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsMethodNotAllowedErrorResponseBody:
      description: Method not allowed
      properties:
        message:
          description: Message of error
          example: DELETE not allowed on /endpoint.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsUnauthorizedErrorResponseBody:
      description: Unauthorized
      properties:
        message:
          description: Message of error
          example: Invalid token.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsNotFoundErrorResponseBody:
      description: Resource not found
      properties:
        message:
          description: Message of error
          example: Object not found.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsInternalServerErrorResponseBody:
      description: An internal server error occurred
      properties:
        message:
          description: Message of error
          example: Failed to execute GraphQL query.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsGatewayTimeoutErrorResponseBody:
      description: Gateway timeout
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    IdlingReportsGetVehicleIdlingReportsNotImplementedErrorResponseBody:
      description: Requested endpoint is not yet implemented
      properties:
        message:
          description: Message of error
          example: Not implemented.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    GoaPaginationResponseResponseBody:
      description: Pagination parameters.
      properties:
        endCursor:
          description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
          example: MjkY
          type: string
        hasNextPage:
          description: True if there are more pages of results immediately available after this endCursor.
          example: true
          type: boolean
      required:
      - endCursor
      - hasNextPage
      type: object
    GoaVehicleTinyResponseResponseBody:
      description: A minified vehicle object. This object is only returned if the route is assigned to the vehicle.
      properties:
        externalIds:
          additionalProperties:
            type: string
          description: A map of external ids
          type: object
        id:
          description: ID of the vehicle
          example: '494123'
          type: string
        name:
          description: Name of the vehicle
          example: 'Fleet Truck #1'
          type: string
      type: object
    IdlingReportsGetVehicleIdlingReportsServiceUnavailableErrorResponseBody:
      description: Service unavailable
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true