Search docs ⌘K
esc
Type to search across all documentation pages
Logistics

Tracking

Record GPS pings against entities. Pings are stored in a Durable Object for real-time access and can be queried as a history trail. All routes live under /logistics/* and require a token with logistics:read or logistics:write scope.

Send Ping

GET
typescript
await ss.logistics.tracking.ping('ent_abc123', {
  lat: 40.7128, lng: -74.0060,
  speed: 35, heading: 90,
})
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. The entity's current position updates in real time on the map
Pings are typically sent from device SDKs or backend services, not from the dashboard.
Path param
Type
Description
entity_id required
string
Entity ID to update
Body field
Type
Description
lat required
number
Latitude (−90 to 90)
lng required
number
Longitude (−180 to 180)
heading
number
Compass heading in degrees (0–360)
speed
number
Speed in km/h (≥ 0)
accuracy
number
GPS accuracy in meters (≥ 0)
recorded_at
string
ISO 8601 timestamp when the ping was recorded. Defaults to server time.
Error responses
400 Invalid body (validation error)
401 Unauthorized
402 Insufficient Tokens
404 Entity not found
429 Rate Limited

Batch Ping

GET
typescript
await ss.logistics.tracking.batchPing('ent_abc123', [
  { lat: 40.7128, lng: -74.0060, recorded_at: '2026-03-08T10:00:00Z' },
  { lat: 40.7135, lng: -74.0055, recorded_at: '2026-03-08T10:01:00Z' },
])
  1. Batch ping is an API-only operation for uploading historical GPS data
  2. Use the REST API or TypeScript SDK
Uploaded pings appear in the Tracking history view.
Path param
Type
Description
entity_id required
string
Entity ID to update
Body field
Type
Description
pings required
array
Array of ping objects (1–100 items). Each ping has: lat (−90 to 90, required), lng (−180 to 180, required), heading (0–360), speed (≥ 0), accuracy (≥ 0), recorded_at (ISO 8601)
Error responses
400 Invalid body (validation error)
401 Unauthorized
402 Insufficient Tokens
404 Entity not found
429 Rate Limited

Live Tracking

GET
typescript
// WebSocket connection for real-time tracking
const ws = ss.logistics.tracking.live('ent_abc123')
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. The map shows the entity's live position and trail in real time
Path param
Type
Description
entity_id required
string
Entity ID to track
Error responses
401 Unauthorized
402 Insufficient Tokens
429 Rate Limited

Ping History

GET
typescript
const trail = await ss.logistics.tracking.history('ent_abc123', { limit: 100 })
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. Switch to the History tab to see the GPS trail plotted on the map
Path param
Type
Description
entity_id required
string
Entity ID
Query param
Type
Description
limit
integer
Max pings to return (1–200). Default 50.
cursor
string
Pagination cursor from previous response
Error responses
401 Unauthorized
402 Insufficient Tokens
429 Rate Limited