Skip to main content
The Data API is a REST API that retrieves or writes data stored on Kameleoon’s remote servers. Use the available endpoints to:
  • Retrieve visit events for a given visitor.
  • Send additional visit events for a given visitor, such as offline conversion events.
  • Send and retrieve product data for a given sitecode.
  • Store additional data for a given visitor, such as CRM or segmentation data.

​
Try the Data API in Postman

Test Data API requests without writing code by using the Kameleoon Data API collection in Postman. The collection has one request for each endpoint, and each request returns a 200 response once you set the variables. To use the collection:
  1. Download the Kameleoon Data API collection as a ZIP archive, extract the JSON file, then import it into Postman.
  2. In the collection’s Variables tab, set baseUrl to the host for your project and siteCode to your project’s site code.
  3. To call POST /visit/forget, also enter clientId and clientSecret, which you get through the Automation API authentication flow, then send Get access token. The request saves the token in the accessToken variable.
  4. Send any other request.

​
Data API endpoints

Endpoints fall into three main categories of data:

​
Visit endpoints

The Visit endpoints retrieve and send events (conversions, custom data, segments, and more) for a given visitor code. Use these endpoints to import offline purchase data, such as physical store purchases, to Kameleoon.
  • GET /visit/visitor: This endpoint retrieves visits data collected by Kameleoon, such as experiments and personalizations triggered for the user or targeted segments.
Access to this endpoint requires the Kameleoon Feature Experimentation solution. For more details, contact the Customer Success Manager.
  • POST /visit/forget: This endpoint removes data for several visitors. The endpoint always requires authentication, so call it from your servers, never from a browser.
  • POST /visit/events: This endpoint posts data for a given visitor, such as conversion and page view events.

​
Product endpoints

The Product endpoints retrieve and send product data for a given sitecode. Use these endpoints to register product events such as view, add to cart, or purchase, or to obtain statistics about specific products such as historical buy or view counts.
  • POST /product/events: This endpoint posts product attributes and events (view, add to cart, and purchase) for several products. The Activation API uses the obtainProductData and obtainProductInteractions methods to retrieve and use this data for targeting or recommendations.
  • GET /product/productCounters: This endpoint retrieves counts (number of views, add to cart quantities, transaction quantities) for several products.
  • GET /product/productData: This endpoint retrieves attributes for several products.
You need access to the Product Recommendation module or the Product Targeting add-on. Both integrate with the Web Experimentation solution. For more information, contact the Customer Success Manager.

​
Map endpoints

The Map endpoints store additional data for a given key (usually a visitor code or an internal User ID). The Activation API and all SDKs use the retrieveDataFromRemoteSource method to retrieve and use this data for targeting and segmentation. Use the map endpoint to retrieve stored data for a specific key.

​
Data API hosts

Data API requests go to a host that depends on your project’s region and domain. Kameleoon hosts projects in Europe and North America, and each region has a host on the kameleoon.io domain and on the kameleoon.eu domain. A request sent to the host of the wrong region receives an HTTP 308 redirect to the correct host. To avoid the redirect, use the host from the Location header as your base URL.

​
Choose a domain

Both domains reach the same servers, so the domain doesn’t change how requests behave. Projects created more recently use kameleoon.io, and older projects use kameleoon.eu. Use the domain that matches your project’s code snippet.

​
Find your domain

To find the domain of your project:
  1. Click Admin > Projects > Edit > Setup.
  2. In your code snippet, find the src address, which looks like //<siteCode>.kameleoon.io/engine.js.
  3. Read the domain after your site code: kameleoon.io or kameleoon.eu.

​
Authentication and rate limiting

​
Authentication

By default, most Data API endpoints don’t require authentication, because the Data API supports the Web Experimentation engine in retrieving historical data. The exception is POST /visit/forget, which always requires authentication. To authenticate, the Data API uses the same flow as the Automation API, with JSON web tokens. Maintain security and protect API credentials by using authentication for specific types of requests:
  • Server-side sources: For requests from your servers, Kameleoon strongly recommends authentication, which also increases rate limits. Authenticate when using server-side SDKs with Feature Experimentation.
  • Client-side sources: For requests from a client app such as a web browser, which could expose API credentials, don’t authenticate. Kameleoon doesn’t recommend this configuration when using Web Experimentation. Client-side sources can’t call POST /visit/forget, because that endpoint requires a token. Call it only from your servers.
Any request providing an API token with an incorrect format, an expired token, or an invalid signature results in an HTTP 401 “Unauthorized” response. To learn more about the authentication process, refer to the Automation API Authentication Flow documentation.
If you use Feature Experimentation and server-side SDKs exclusively, contact the Customer Success Manager to enable authentication for specific endpoints. Kameleoon offers a flexible setup to secure endpoints and restrict authentication to GET or POST requests.

​
Rate limits

The Data API enforces rate limits based on your Contractual Monthly Unique Visitors (MUV) and your IP address. If your app exceeds either of these limits, the API returns an HTTP 429 - “Too Many Requests” response. These rate limits keep the Kameleoon service performant and reliable for all customers. You can lift the IP-based limits for server-side sources by authenticating. In environments where many visitors share a single IP address, such as offices or corporate networks, the IP-based limits can apply even when your overall MUV stays within contract. Where multiplier depends on your subscription:
  • 1: You use only one solution, either Web Experimentation or Feature Experimentation
  • 2: You use both Web Experimentation and Feature Experimentation
If you require higher rate limits for your use case, contact your Account Manager for more information.
Kameleoon automatically detects known bot traffic and excludes it from rate limit calculations. Requests identified as coming from bots don’t count towards either the GET or POST limits in the table preceding.

​
What generates requests

Understanding which operations generate GET and POST requests helps you estimate and manage your rate limit consumption. The breakdown below primarily applies to client-side technologies (engine.js, the JavaScript SDK, and mobile SDKs), where each device issues its own requests. For POST tracking requests, server-side SDKs are more efficient at scale because they can batch data for multiple visitors into a single request. GET requests always target a single visitor. Your app triggers GET requests only when it explicitly calls one of the following operations. The SDK and engine perform no automatic polling:
  • Visitor data fetches: getRemoteVisitorData() (SDKs) or performRemoteSynchronization() (engine.js) loads remote visitor data for a specific visitor on demand.
  • Remote data and warehouse audience fetches: getVisitorWarehouseAudience() (SDKs) or retrieveDataFromRemoteSource() (SDKs and engine.js) loads data warehouse or remote map data on demand.
POST requests come from the tracking mechanism, which batches visitor data before sending:
  • Tracking requests: The primary recurring POST call. The SDK or engine batches pending visitor data and sends it at most once per tracking interval, only when there is pending data to flush. The default interval is 1 second. In SDKs, you can configure the interval between 1 and 5 seconds using trackingIntervalMillisecond / tracking_interval_millisecond; engine.js uses a fixed 500-millisecond interval. Conversions, tracked feature flag evaluations, and explicit flush() calls all queue data for the next interval, or send immediately if you trigger an instant flush.
  • Activity tracking: A secondary mechanism that contributes visitor activity data (clicks, scrolls, and mouse moves) into the next tracking send. The SDK only collects activity data while the user is active on the active tab. The default interval is 60 seconds. In SDKs, you can configure the interval using activityTrackingIntervalMillisecond / activity_tracking_interval_millisecond; engine.js uses a fixed 60-second interval.
For mobile SDKs: periodic tracking pauses automatically when the app moves to the background. An explicit immediate flush can still send any pending data regardless of app state. For the JavaScript SDK: the tracking request only goes out when the visitor has genuinely interacted with the page (through mouse movement or scrolling) since the last interval tick, preventing hidden or backgrounded tabs from inflating visit counts. To continue sending data while the page isn’t active, explicitly call flush({instant: true}). When the Kameleoon Engine (window.Kameleoon) is also present on the page, the SDK prevents duplicate activity tracking.

​
Account-level limits

Rate limits apply to your entire customer account, not to individual projects. If one project generates excessive requests (for example, because a faulty implementation creates a loop that sends custom data events repeatedly), that project consumes the shared account limit and can cause HTTP 429 errors across all your other projects.

​
Diagnose excessive request volume

Use the Live events page (Insights > Live events) to identify which project is generating unexpected traffic:
  1. Check event volume by project: Select each project in turn and review its event count over the past hour or 24 hours. A project generating far more events than its visitor volume justifies (for example, tens of millions of events against a 100,000 MUV contract) is the likely source.
  2. Filter by event type: Once you identify the suspect project, filter events by type. Custom data events are the most common cause of unexpected volume. A misconfigured implementation can create a loop that sends the same custom data variable, or all custom data variables, on every page load, producing a large number of events in a short time.

​
Check your request count

Use the Automation API’s Data API request endpoints to see exactly where your Data API request volume comes from before it approaches your rate limit:
  • By endpoint: GET /data-api-requests/by-endpoint returns the number of requests sent to the Data API for a given site, broken down by day, HTTP method, path, and status code. Use this endpoint to identify which integration or endpoint drives your traffic.
  • By source: GET /data-api-requests/by-source returns the number of requests sent to the Data API for a given site, broken down by day and source (Engine, SDK: <name>, or Direct). Use this endpoint to identify which client type drives your traffic.
Both endpoints take the same three required query parameters:
The range between from and to can’t exceed 7 days.
Authenticate with an OAuth 2.0 bearer token, following the same Automation API authentication flow used for other Automation API calls. To break down request volume by HTTP method, path, and status code:
curl
To break down request volume by source:
curl
Run this check whenever Live events shows unexpected traffic, to confirm which HTTP methods, paths, status codes, or sources make up your request volume.