Fleet Delta
Efficiently synchronize changes across your entire tag fleet
Overview
Fleet Delta is the most efficient endpoint for synchronizing your workspace's tag fleet. Instead of polling individual tags or fetching all tags repeatedly, it returns only the tags whose location advanced since your last sync.
This is the recommended endpoint for polling and for reconciliation when combined with webhooks.
How It Works
Fleet Delta uses a cursor-based approach: you provide a timestamp from your last sync, and the API returns only tags that changed since that point. Each item is a compact fleet delta record (note the field is tagId, and the full location point is under location).
GET /v1/fleet/delta?since=2024-06-19T12:00:00Z
{
"data": [
{
"tagId": "aB3xK9Qm1Zr7",
"name": "Van 1",
"originalPhysicalLabel": "01",
"labels": ["Coca-Cola", "Seattle"],
"hardwareId": "00000000DEADBEEF",
"lastSeenAt": "2024-06-19T13:45:23Z",
"recordingPaused": false,
"battery": { "level": null, "status": 1, "updatedAt": "2024-06-19T13:45:23Z" },
"location": {
"lat": 40.7128,
"lng": -74.0060,
"timestamp": "2024-06-19T13:45:23Z",
"timestampMs": 1718809523000,
"accuracy": 25
}
}
],
"nextCursor": "cursor_def456"
}The location object is abbreviated above for readability. Each item returns a full location point — see Locations for every field.
Parameters
since
ISO 8601 timestamp or epoch milliseconds. Returns only tags whose location advanced after this time. Optional—omit it to receive a full snapshot of every tag that has reported a location.
limit
Page size (default 100, max 500).
cursor
Pagination token. Use nextCursor from a previous response to fetch the next page.
Response Fields
data
Array of fleet delta items. Each item has tagId, name, read-only originalPhysicalLabel, workspace-defined labels, hardwareId, lastSeenAt, recordingPaused, battery, and location (a full location point, or null when there is no fix). See Locations for the location point shape.
nextCursor
Pagination token for the next page. Null if there are no more results.
Usage Patterns
Initial Sync
To fetch the current state of every tag that has reported a location, omit since (or pass a timestamp far in the past):
const response = await fetch(
'https://api.taglogger.com/v1/fleet/delta?limit=500',
{ headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);Periodic Polling
Store the timestamp of your last sync and use it for the next poll:
let lastSync = new Date();
async function syncFleet() {
const response = await fetch(
`https://api.taglogger.com/v1/fleet/delta?since=${lastSync.toISOString()}`,
{ headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);
const { data, nextCursor } = await response.json();
let maxSeen = lastSync;
for (const item of data) {
updateLocalDatabase(item.tagId, item.location);
const seen = new Date(item.lastSeenAt);
if (seen > maxSeen) maxSeen = seen;
}
// Carry forward the newest lastSeenAt we saw, not wall-clock — advancing
// by new Date() can skip changes that arrive between polls.
lastSync = maxSeen;
}
// Poll every 30 seconds
setInterval(syncFleet, 30000);Pagination
For large workspaces, results may be paginated. Fetch all pages:
let cursor = null;
let allItems = [];
do {
const query = new URLSearchParams({ since: '2024-06-19T00:00:00Z', limit: 500 });
if (cursor) query.set('cursor', cursor);
const response = await fetch(
`https://api.taglogger.com/v1/fleet/delta?${query}`,
{ headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);
const { data, nextCursor } = await response.json();
allItems = allItems.concat(data);
cursor = nextCursor;
} while (cursor);When to Use
- Regular polling: Use Fleet Delta instead of fetching individual tags or listing all tags every time.
- Webhook reconciliation: Combine webhooks with periodic Fleet Delta polls to ensure you never miss an update.
- Multiple tags: For any workspace with more than a few tags, Fleet Delta is more efficient than single-tag endpoints.
- App syncing: Keep your app's view of the fleet in sync with the server.
Efficiency Tips
- Use appropriate poll intervals: 30–60 seconds is fine for most use cases; more frequent polls waste quota.
- Store the sync timestamp: Persist lastSync so you resume from the right point if your service restarts.
- Handle pagination: Use the limit parameter (max 500) to fetch large result sets efficiently.
- Respect rate limits: Monitor X-RateLimit-* headers and back off if you're close to your limit.
- Combine with webhooks: For real-time responsiveness, use webhooks + periodic Fleet Delta polling for reconciliation.