HomeEngagementOther resources
API reference

Tracking API overview

/track/v2/projects/{projectToken}

Use the Tracking API to update customer and event properties in your Bloomreach project in real time. This API is built for live data tracking and timestamp retrieval for immediate processing needs.

🚧

Important

Only use this API for real-time tracking. Don't use it for large scheduled imports, as 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 caused by 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, the following happens:

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

Why rate limits exist

Rate limits protect against integration errors that could:

  • Generate excessive duplicate events, such as 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

Handle 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.

Troubleshoot 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 a limit increase request.

📘

Note

The error response structure and common Tracking API errors are listed in the Tracking API error messages guide.

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.