Developer API
Developer APIGuides & ExamplesBatch Operations

Batch Operations and Pagination

Efficiently work with multiple tags and handle large result sets

Listing All Tags

To fetch all your tags in one call, use the GET /v1/tags endpoint:

const response = await fetch('https://api.taglogger.com/v1/tags', {
  headers: { 'Authorization': 'Bearer tl_live_xxx' }
});

const { data, nextCursor } = await response.json();
console.log(`Found ${data.length} tags`);

// data is an array of tag objects with id, name, status, hardwareId, etc.

Fleet Delta for Changes

For the most efficient batch retrieval, use the Fleet Delta endpoint. It returns only the tags that have changed since your last sync, saving bandwidth:

const response = await fetch(
  'https://api.taglogger.com/v1/fleet/delta?since=2024-06-19T12:00:00Z',
  { headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);

const { data, nextCursor } = await response.json();
console.log(`${data.length} tags changed`);

// data includes tags whose location advanced since 'since'

Pagination

List endpoints return paginated results. Use the nextCursor field to fetch additional pages:

let cursor = null;
let allTags = [];

do {
  const query = new URLSearchParams({ limit: 200 });
  if (cursor) query.set('cursor', cursor);

  const response = await fetch(
    `https://api.taglogger.com/v1/tags?${query}`,
    { headers: { 'Authorization': 'Bearer tl_live_xxx' } }
  );

  const { data, nextCursor } = await response.json();
  allTags = allTags.concat(data);
  cursor = nextCursor;

  console.log(`Fetched ${data.length} tags, nextCursor: ${cursor || 'none'}`);
} while (cursor);

console.log(`Total: ${allTags.length} tags`);

limit: Page size (default 50, max 200). cursor: Opaque token for the next page. nextCursor: null when there are no more pages.

Batch Reading Current Locations

To get current locations for multiple tags:

  1. Call GET /v1/tags to list all tags
  2. Or use GET /v1/fleet/delta to get only changed tags
  3. Extract the current location from each tag's lastLocation field

Each tag object includes lastLocation (current latitude, longitude, and timestamp), so you don't need additional requests. For accuracy, altitude, and other detail, call the location or history endpoints.

Parallel Requests for Details

If you need detailed history for specific tags, make parallel requests to avoid sequential delays:

const tagIds = ['tag_abc', 'tag_def', 'tag_ghi'];
const headers = { 'Authorization': 'Bearer tl_live_xxx' };

// Fetch history for all tags in parallel
const histories = await Promise.all(
  tagIds.map(id =>
    fetch(`https://api.taglogger.com/v1/tags/${id}/history?limit=100`, { headers })
      .then(r => r.json())
  )
);

// Process results
for (let i = 0; i < tagIds.length; i++) {
  console.log(`Tag ${tagIds[i]}: ${histories[i].data.length} history points`);
}

Rate Limiting with Batch Operations

Batch operations can quickly hit rate limits. Monitor the rate-limit headers and implement backoff:

async function fetchWithBackoff(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, {
      headers: { 'Authorization': 'Bearer tl_live_xxx' }
    });

    const remaining = response.headers.get('X-RateLimit-Remaining');
    const reset = response.headers.get('X-RateLimit-Reset');

    console.log(`Rate limit: ${remaining} remaining, resets at ${reset}`);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delayMs = (parseInt(retryAfter) || 60) * 1000;
      console.log(`Rate limited. Waiting ${delayMs}ms`);
      await new Promise(r => setTimeout(r, delayMs));
      continue;
    }

    if (response.ok) {
      return response.json();
    }

    throw new Error(`HTTP ${response.status}`);
  }

  throw new Error(`Failed after ${maxRetries} attempts`);
}

Best Practices

  • Use Fleet Delta: When syncing regularly, it's much more efficient than listing all tags every time.
  • Respect pagination: Always check for nextCursor and fetch all pages.
  • Parallel requests: Use Promise.all for independent requests, but stay below rate limits.
  • Monitor rate limits: Log X-RateLimit-* headers to understand your usage and adjust request frequency.
  • Implement exponential backoff: When hitting rate limits, wait longer between retries (1s, 2s, 4s, etc.).
  • Cache results: Store tag data locally and only poll on an interval to avoid unnecessary requests.
  • Use appropriate page sizes: Use a large page size (up to 200 for list endpoints, 500 for fleet delta, 1000 for history) to minimize pagination overhead.
  • Batch by operation type: Group similar requests (all list, all history) rather than interleaving them.

See Also