Usage & Rate Limits
Understand metering, rate limits, and how to optimize API usage
Rate Limiting
Each API key is limited to 120 requests per 60-second window. The window is fixed per key, and every request counts toward the limit regardless of the endpoint or response status.
If you are regularly close to the limit, the Optimizing Usage patterns below—fleet delta, webhooks, and local caching—keep most fleets comfortably under it without any change to your key.
Checking Your Limit
Every response includes rate-limit information in the headers:
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1718900460
{ "data": [...] }X-RateLimit-Limit: Maximum requests allowed in the current window for your key.
X-RateLimit-Remaining: Requests remaining before hitting the limit.
X-RateLimit-Reset: Unix timestamp (seconds) when the limit resets.
Exceeding the Limit
When you exceed your rate limit, requests fail with 429 Too Many Requests:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718900460
Retry-After: 12
{ "error": { "code": "rate_limited", "message": "Rate limit of 120 requests per 60s exceeded." } }Retry-After: Seconds to wait before retrying. Always respect this header.
Optimizing Usage
To stay within rate limits and reduce unnecessary API calls:
Use Fleet Delta
Instead of polling individual tags, use GET /v1/fleet/delta to fetch only changed tags in a single request.
Increase Poll Interval
If you're polling regularly, increase the interval. 30–60 seconds is reasonable for most use cases. Real-time dashboards might use 5–10 seconds, but background jobs can poll every 5–10 minutes.
Use Webhooks
Webhooks are much more efficient than polling. You only receive notifications when tags actually change, rather than making regular requests regardless of whether anything happened.
Cache Locally
Store tag data in your local database or cache. Only update when the API returns fresh data, and avoid fetching the same information multiple times.
Batch Requests
When fetching data for multiple tags, use GET /v1/tags (with pagination) instead of multiple individual GET /v1/tags/{tagId} requests.
Example: Rate-Limit Aware Polling
async function pollWithBackoff(since) {
let backoffMs = 1000; // Start with 1 second backoff
while (true) {
try {
const response = await fetch(
`https://api.taglogger.com/v1/fleet/delta?since=${since}`,
{ headers: { 'Authorization': 'Bearer tl_live_xxx' } }
);
// Log rate limit info
const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
console.log(`Rate limit: ${remaining}/${limit}`);
if (response.status === 429) {
const retryAfter = parseInt(response.headers.get('Retry-After')) || 60;
console.warn(`Rate limited. Waiting ${retryAfter}s`);
await sleep(retryAfter * 1000);
continue;
}
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const { data, nextCursor } = await response.json();
processChanges(data);
backoffMs = 1000; // Reset on success
return;
} catch (error) {
console.error('Poll error:', error);
await sleep(backoffMs);
backoffMs = Math.min(backoffMs * 2, 30000); // Cap at 30s
}
}
}
function sleep(ms) {
return new Promise(r => setTimeout(r, ms));
}Monitoring Your Usage
The clearest real-time signal is the rate-limit headers on every response. Track X-RateLimit-Remaining to see how close you are to your limit and adjust your request rate before you hit it.
There is no separate usage dashboard in v1—the rate-limit headers on every response are the live usage signal. Log X-RateLimit-Remaining from your own client to chart usage over time and alert before you approach the limit.
Need More Throughput?
If you're consistently close to the standard limit of 120 requests per 60 seconds, the most effective fix is on the integration side: poll GET /v1/fleet/delta instead of per-tag endpoints, switch from polling to webhooks, and cache locally. The patterns in Optimizing Usage above keep most fleets well under the limit.
Best Practices
- Monitor X-RateLimit-Remaining: Check this header and adjust your polling frequency if you're consistently close to the limit.
- Implement exponential backoff: When hitting rate limits, wait exponentially longer between retries (1s, 2s, 4s, 8s, etc.).
- Use Fleet Delta: It's much more efficient than polling individual tags or listing all tags repeatedly.
- Cache aggressively: Store tag data locally and only refresh on webhooks or a periodic poll.
- Use webhooks: They're more efficient than polling and give you immediate notifications.
- Batch related requests: Fetch all the data you need in one go, rather than making multiple small requests.
- Avoid rapid retries: If a request fails, don't immediately retry. Back off first.