openapi: 3.0.1 info: description: Gain greater visibility by connecting your fleets, equipment, sites, and people. title: Samsara Fuel API version: '2024-11-18' servers: - url: https://api.samsara.com/ - url: https://api.eu.samsara.com/ security: - AccessTokenHeader: [] tags: - name: Fuel paths: /fleet/reports/drivers/fuel-energy: get: description: "Get fuel and energy efficiency driver reports for the requested time range.\n\n Rate limit: 5 requests/sec (learn more about rate limits here).\n\nTo use this endpoint, select **Read Fuel & Energy** under the Fuel & Energy category when creating or editing an API token. Learn More.\n \n\n **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." operationId: getFuelEnergyDriverReports parameters: - description: A start date in RFC 3339 format. This parameter ignores everything (i.e. hour, minutes, seconds, nanoseconds, etc.) besides the date and timezone. If no time zone is passed in, then the UTC time zone will be used. This parameter is inclusive, so data on the date specified will be considered. 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. For example, 2022-07-13T14:20:50.52-07:00 is a time in Pacific Daylight Time. in: query name: startDate required: true schema: type: string - description: An end date in RFC 3339 format. This parameter ignores everything (i.e. hour, minutes, seconds, nanoseconds, etc.) besides the date and timezone. If no time zone is passed in, then the UTC time zone will be used. This parameter is inclusive, so data on the date specified will be considered. 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. For example, 2022-07-13T14:20:50.52-07:00 is a time in Pacific Daylight Time. in: query name: endDate required: true schema: type: string - description: ' A filter on the data based on this comma-separated list of driver IDs and externalIds. Example: `driverIds=1234,5678,payroll:4841`' explode: false in: query name: driverIds schema: items: type: string type: array style: form - 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: ' 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 responses: '200': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsResponseBody' description: OK response. '401': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsUnauthorizedErrorResponseBody' description: Unauthorized response. '404': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsNotFoundErrorResponseBody' description: Not Found response. '405': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsMethodNotAllowedErrorResponseBody' description: Method Not Allowed response. '429': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsTooManyRequestsErrorResponseBody' description: Too Many Requests response. '500': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsInternalServerErrorResponseBody' description: Internal Server Error response. '501': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsNotImplementedErrorResponseBody' description: Not Implemented response. '502': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsBadGatewayErrorResponseBody' description: Bad Gateway response. '503': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsServiceUnavailableErrorResponseBody' description: Service Unavailable response. '504': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsGatewayTimeoutErrorResponseBody' description: Gateway Timeout response. default: content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyDriverReportsBadRequestErrorResponseBody' description: Bad Request response. summary: Get Fuel and Energy Efficiency Driver Reports. tags: - Fuel /fleet/reports/vehicles/fuel-energy: get: description: "Get fuel and energy efficiency vehicle reports for the requested time range.\n\n Rate limit: 25 requests/sec (learn more about rate limits here).\n\nTo use this endpoint, select **Read Fuel & Energy** under the Fuel & Energy category when creating or editing an API token. Learn More.\n \n\n **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." operationId: getFuelEnergyVehicleReports parameters: - description: A start date in RFC 3339 format. This parameter ignores everything (i.e. hour, minutes, seconds, nanoseconds, etc.) besides the date and timezone. If no time zone is passed in, then the UTC time zone will be used. This parameter is inclusive, so data on the date specified will be considered. 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. For example, 2022-07-13T14:20:50.52-07:00 is a time in Pacific Daylight Time. in: query name: startDate required: true schema: type: string - description: An end date in RFC 3339 format. This parameter ignores everything (i.e. hour, minutes, seconds, nanoseconds, etc.) besides the date and timezone. If no time zone is passed in, then the UTC time zone will be used. This parameter is inclusive, so data on the date specified will be considered. 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. For example, 2022-07-13T14:20:50.52-07:00 is a time in Pacific Daylight Time. in: query name: endDate 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: 'The type of energy used by the vehicle. Valid values: `fuel`, `hybrid`, `electric`' in: query name: energyType schema: enum: - fuel - hybrid - electric 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: ' 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 responses: '200': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsResponseBody' description: OK response. '401': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsUnauthorizedErrorResponseBody' description: Unauthorized response. '404': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsNotFoundErrorResponseBody' description: Not Found response. '405': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsMethodNotAllowedErrorResponseBody' description: Method Not Allowed response. '429': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsTooManyRequestsErrorResponseBody' description: Too Many Requests response. '500': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsInternalServerErrorResponseBody' description: Internal Server Error response. '501': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsNotImplementedErrorResponseBody' description: Not Implemented response. '502': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsBadGatewayErrorResponseBody' description: Bad Gateway response. '503': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsServiceUnavailableErrorResponseBody' description: Service Unavailable response. '504': content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsGatewayTimeoutErrorResponseBody' description: Gateway Timeout response. default: content: application/json: schema: $ref: '#/components/schemas/FuelEnergyGetFuelEnergyVehicleReportsBadRequestErrorResponseBody' description: Bad Request response. summary: Get Fuel and Energy Efficiency Vehicle Reports. tags: - Fuel components: schemas: FuelEnergyCostResponseResponseBody: description: Estimated cost of fuel and energy over the given time range. properties: amount: description: Amount of the currency. example: 94.01 format: double type: number currencyCode: description: Type of the currency. example: USD type: string required: - amount - currencyCode type: object FuelEnergyGetFuelEnergyVehicleReportsMethodNotAllowedErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsGatewayTimeoutErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsServiceUnavailableErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsGatewayTimeoutErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsBadGatewayErrorResponseBody: 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 FuelEnergyDriverReportDataObjectResponseBody: description: Dictionary containing summarized driver report data. properties: driverReports: description: List of summarized driver reports. items: $ref: '#/components/schemas/FuelEnergyDriverReportObjectResponseBody' type: array required: - driverReports type: object FuelEnergyGetFuelEnergyDriverReportsInternalServerErrorResponseBody: 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 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 FuelEnergyGetFuelEnergyVehicleReportsNotImplementedErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsTooManyRequestsErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsUnauthorizedErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsTooManyRequestsErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsResponseBody: properties: data: $ref: '#/components/schemas/FuelEnergyDriverReportDataObjectResponseBody' pagination: $ref: '#/components/schemas/GoaPaginationResponseResponseBody' required: - data - pagination type: object FuelEnergyGetFuelEnergyDriverReportsNotImplementedErrorResponseBody: 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 FuelEnergyVehicleReportDataObjectResponseBody: description: Dictionary containing summarized vehicle report data. properties: vehicleReports: description: List of summarized vehicle reports. items: $ref: '#/components/schemas/FuelEnergyVehicleReportObjectResponseBody' type: array required: - vehicleReports type: object FuelEnergyGetFuelEnergyDriverReportsNotFoundErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsBadGatewayErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsUnauthorizedErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsMethodNotAllowedErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsResponseBody: properties: data: $ref: '#/components/schemas/FuelEnergyVehicleReportDataObjectResponseBody' pagination: $ref: '#/components/schemas/GoaPaginationResponseResponseBody' required: - data - pagination type: object FuelEnergyGetFuelEnergyVehicleReportsBadRequestErrorResponseBody: 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 FuelEnergyVehicleObjectResponseBody: description: A minified vehicle object. properties: energyType: description: 'Type of energy used by the vehicle Valid values: `fuel`, `hybrid`, `electric`' enum: - fuel - hybrid - electric example: fuel type: string 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 required: - energyType type: object GoaDriverTinyResponseResponseBody: description: A minified driver object. This object is only returned if the route is assigned to the driver. properties: externalIds: additionalProperties: type: string description: A map of external ids type: object id: description: ID of the driver example: '45646' type: string name: description: Name of the driver example: Driver Bob type: string required: - id type: object FuelEnergyVehicleReportObjectResponseBody: description: A summary of this vehicle's fuel and energy data. properties: distanceTraveledMeters: description: Meters traveled over the given time range. example: 1384000 format: double type: number efficiencyMpge: description: Efficiency in MPG or MPGE over the given time range. For fuel vehicles this will be provided in MPG, for hybrid and electric vehicles this will be provided in MPGE. MPG/MPGE values are provided based on US gallons. example: 21.4 format: double type: number energyUsedKwh: description: Kilowatt-hours of energy used over the given time range. Only provided for hybrid and electric vehicles. example: 73.2 format: double type: number engineIdleTimeDurationMs: description: Milliseconds of engine idle time over the given time range. Only provided for fuel and hybrid vehicles. example: 4320000 format: int64 type: integer engineRunTimeDurationMs: description: Milliseconds of engine run time over the given time range. Only provided for fuel and hybrid vehicles. example: 576000 format: int64 type: integer estCarbonEmissionsKg: description: Estimated kilograms of carbon emissions over the given time range. Only provided for fuel and hybrid vehicles. example: 22.7 format: double type: number estFuelEnergyCost: $ref: '#/components/schemas/FuelEnergyCostResponseResponseBody' fuelConsumedMl: description: Milliliters of fuel consumed over the given time range. Only provided for fuel and hybrid vehicles. example: 162773 format: double type: number vehicle: $ref: '#/components/schemas/FuelEnergyVehicleObjectResponseBody' required: - distanceTraveledMeters - efficiencyMpge - estFuelEnergyCost - vehicle type: object FuelEnergyGetFuelEnergyVehicleReportsInternalServerErrorResponseBody: 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 FuelEnergyGetFuelEnergyDriverReportsBadRequestErrorResponseBody: 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 FuelEnergyGetFuelEnergyVehicleReportsNotFoundErrorResponseBody: 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 FuelEnergyDriverReportObjectResponseBody: description: A summary of this driver's fuel and energy data. properties: distanceTraveledMeters: description: Meters traveled over the given time range. example: 1384000 format: double type: number driver: $ref: '#/components/schemas/GoaDriverTinyResponseResponseBody' efficiencyMpge: description: Efficiency in MPG or MPGE over the given time range. For fuel vehicles this will be provided in MPG, for hybrid and electric vehicles this will be provided in MPGE. MPG/MPGE values are provided based on US gallons. example: 21.4 format: double type: number energyUsedKwh: description: Kilowatt-hours of energy used over the given time range. Only provided for hybrid and electric vehicles. example: 73.2 format: double type: number engineIdleTimeDurationMs: description: Milliseconds of engine idle time over the given time range. Only provided for fuel and hybrid vehicles. example: 4320000 format: int64 type: integer engineRunTimeDurationMs: description: Milliseconds of engine run time over the given time range. Only provided for fuel and hybrid vehicles. example: 576000 format: int64 type: integer estCarbonEmissionsKg: description: Estimated kilograms of carbon emissions over the given time range. Only provided for fuel and hybrid vehicles. example: 22.7 format: double type: number estFuelEnergyCost: $ref: '#/components/schemas/FuelEnergyCostResponseResponseBody' fuelConsumedMl: description: Milliliters of fuel consumed over the given time range. Only provided for fuel and hybrid vehicles. example: 162773 format: double type: number required: - distanceTraveledMeters - driver - efficiencyMpge - estFuelEnergyCost type: object FuelEnergyGetFuelEnergyDriverReportsServiceUnavailableErrorResponseBody: 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