Skip to main content

​
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 and regional API guide for token and region details.

​
Available tools

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 and update semantics.

​
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 and history reference.
  • 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.