> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Samsara

> Connect Samsara fleet visibility and dispatch to your agents

## Connect your fleet

An Aster organization admin can connect one Samsara account in **Control Hub > Integrations > Samsara**. This connection is shared across the organization.

1. In Samsara, open **Settings > API Tokens** and create an API token.
2. Enable **Read Vehicles**, **Read Drivers**, and **Read Vehicle Statistics**. Limit the token to the tags agents should access, if needed.
   For dispatch lookup, also enable **Read Routes**, **Read Assignments**, **Read Addresses**, and **Read Tags**. Enable **Write Routes** for route creation or reassignment tools. Organization tool permissions can restrict write tools independently.
3. Paste the token into Aster and select the region matching your Samsara dashboard: United States (`cloud.samsara.com`), Europe / UK (`cloud.eu.samsara.com`), or Canada (`cloud.ca.samsara.com`). Canadian accounts using the US dashboard should select United States.
4. Save the connection. Aster checks **Read Vehicles** access before saving; an empty fleet is valid. Driver and telemetry scopes are checked when those tools run.
5. Enable the Samsara tools on your agent. Organization tool permissions apply.

See Samsara's [authentication guide](https://developers.samsara.com/docs/authentication) and [regional API guide](https://developers.samsara.com/docs/base-url) for token and region details.

## Available tools

| Tool | Use |
| - | - |
| `samsara_vehicles` | List vehicles, IDs, VINs, and available metadata. |
| `samsara_drivers` | List active drivers, or deactivated drivers with `activation_status`. |
| `samsara_telemetry` | `action=snapshot` reads last-known GPS/telemetry; `action=history` reads events over a time range. |
| `samsara_routes` | `action=list` lists routes in a time range; `action=get` reads one route by `route_id`. |
| `samsara_manage_routes` | `action=create`, `update`, `assign`, or `unassign` manages dispatch routes. Requires Write Routes. |
| `samsara_assignments` | Read driver–vehicle assignments over a time range. |
| `samsara_lookup` | `action=addresses` finds saved addresses/geofences; `action=tags` discovers fleet groups/tag IDs. |

For telemetry, provide `action=snapshot` or `action=history` and select one to three `types`, such as `gps`, `engineStates`, `fuelPercents`, or `obdOdometerMeters`. Other supported types appear in the tool's schema. Times require RFC 3339 format with a timezone, such as `2026-10-16T12:00:00Z`. Filter by `vehicle_ids`, `tag_ids`, or `parent_tag_ids` as supported by each tool.

For `samsara_routes(action=list)`, provide `start_time` and `end_time`; for `action=get`, provide only `route_id`. For `samsara_lookup(action=tags)`, omit address tag filters.

List calls return one page. When `pagination.hasNextPage` is true, pass `next_after` as `after` with the same filters. Large agent results are attached as JSON; the attachment contains the fetched page, not every page in the fleet. Historical readings for a vehicle can span pages. Keep all readings when combining pages. Direct API calls use the shared inline response size limit and do not create conversation attachments.

## Dispatch workflow

Use addresses, tags, vehicles, and drivers to resolve IDs, then list or inspect routes. Driver–vehicle assignments describe driving attribution, which is distinct from route assignment and driver availability. Without an `assignment_type`, assignment results cover vehicle trip time ranges; specify `static` to inspect static assignments outside trips.

`samsara_manage_routes` keeps all route writes in one separately permissioned tool. `action=create` requires `name` and `stops`; `action=update` requires `route_id` and at least one change; `action=assign` requires `route_id` plus `driver_id` or `vehicle_id`; `action=unassign` requires only `route_id`. Read-only `samsara_routes` cannot execute writes.

Route creation supports 2–100 saved-address stops, with departure time at the first stop and arrival times at subsequent stops. The route starts on departure from the first stop and completes on arrival at the last. Assign a driver or a vehicle, never both. Route updates change only names, notes, or assignments. Setting `driver_id` clears the vehicle assignment; `vehicle_id` clears the driver; `action=unassign` clears both. For a combined metadata/assignment update, `action=update` also accepts `unassign=true`.

External IDs help locate a created route, but retries are not assumed idempotent. Writes are never retried automatically. If a write times out or returns an uncertain error, inspect the route (or list the relevant time window) before retrying. Confirmed writes retain `route_id` and `write_succeeded` in the agent's spill summary. See Samsara's [route creation guide](https://developers.samsara.com/docs/creating-routes-via-api) and [update semantics](https://developers.samsara.com/reference/patchroute).

## Example prompts

* “List our vehicles and their VINs.”
* “Where was truck 123 last seen? Include the GPS timestamp.”
* “Show the fuel level and odometer reading for these vehicles.”
* “Pull yesterday's GPS and engine-state readings for truck 123.”
* “Which dispatch routes are still in progress today?”
* “Create tomorrow's delivery route using these saved addresses and assign it to this driver.”
* “Reassign route 123 to vehicle 456.”

## Coverage and troubleshooting

This version covers fleet reads and route creation/reassignment. It does not replace existing route stops, delete routes, modify vehicle or driver records, write driver–vehicle attribution, ingest webhooks, or provide safety and HOS reports. It uses API tokens; marketplace OAuth installation is not included.

Last-known measurements can be stale. Check their timestamps and use a fixed snapshot `time` when paging. Missing readings are unknown, not zero. Cumulative distance, engine-time, and fuel counters require differences to calculate interval usage. See Samsara's [snapshot reference](https://developers.samsara.com/reference/getvehiclestats) and [history reference](https://developers.samsara.com/reference/getvehiclestatshistory).

* **401:** Check the token and dashboard region, then reconnect.
* **403:** Grant the relevant read scope and check tag restrictions.
* **429:** Wait before retrying the same page.
* **Oversized response:** Narrow the time range, vehicle IDs, stat types, or roster page size.

The token stays server-side and is redacted in connection responses. To rotate it, edit the connection; to remove it, disconnect Samsara in Integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.