Samsara Fuel API
The Fuel API from Samsara — 2 operation(s) for fuel.
The Fuel API from Samsara — 2 operation(s) for fuel.
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 <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>).\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: 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 <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: 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