HomeEngagementContentDiscoveryOther resources
API reference

Tracking API overview

/track/v2/projects/{projectToken}

The Tracking API enables real-time manipulation of customer and event properties in your Bloomreach Engagement project. This API handles live data tracking and specific timestamp retrieval for immediate processing needs.

🚧

Important

Only use this API for real-time tracking. Don't use it for large scheduled imports — this strains system performance.

Rate limiting

IP-based rate limits

The Tracking API enforces IP-based rate limiting to protect your project infrastructure and prevent data quality issues from integration errors.

Default rate limit: 6,000 HTTP requests per minute per IP address (100 requests per second per IP).

📘

Note

The actual limit may vary across different instances but will always meet or exceed the default threshold.

Rate limit behavior

When requests from a single IP address exceed the rate limit:

  • Response: HTTP 429 Too Many Requests.
  • Data handling: Request data gets ignored and won't be saved to the platform.
  • Impact scope: Only affects requests from the rate-limited IP address.
  • Other traffic: Requests from different IP addresses continue processing normally.

Why rate limits exist

Rate limiting protects against integration errors that could:

  • Generate excessive duplicate events (like tracking one page view hundreds of times).
  • Consume Monthly Processing Events (MPE) unnecessarily.
  • Create data quality issues.
  • Slow down campaign performance.

The limits accommodate legitimate tracking scenarios. Even with millions of simultaneous website visitors, you're unlikely to reach the per-IP threshold under normal conditions.

Error handling

HTTP 429 responses

When you receive an HTTP 429 Too Many Requests response:

  • Implement exponential backoff: Gradually increase wait times between retry attempts.
  • Reduce request frequency: Send subsequent requests at a slower rate.
  • Monitor integration health: Check for coding errors causing excessive API calls.

Troubleshooting rate limits

If you encounter rate limiting:

  • Review integrations: Check JavaScript SDK, mobile SDKs, and backend integrations for errors.
  • Identify problematic callers: Remember that limits apply per IP address.
  • Contact support: If your API usage is legitimate but hitting limits, reach out to your Customer Success Manager for limit increase requests.

Proxy configurations

When using X-Forwarded-For headers, the API uses the IP address from this header for rate limiting instead of the actual sender address. This ensures rate limits apply per customer endpoint when events route through proxy servers, preventing IP aggregation issues.