Reporting Experiment Exposures via the Tracking API

The /visitors endpoint records that one visitor was exposed to one variant. It is the source of the sessions figure shown per variant on the Statistics page, which makes it the denominator of every conversion rate and the input to every significance calculation on the experiment.

Pertento’s own browser runtime calls this endpoint. You call it directly when your application assigns variants itself, as in a Server Side experiment.

The request

POST https://tracking.pertento.ai/visitors?websiteId=<websiteId>&exp-<experimentId>=<variantId>

Everything is in the query string. There is no request body, no authentication and no origin restriction, so it can be called from a browser or from a server.

A successful call returns:

{ "ok": true }

Parameters

• exp-<experimentId>=<variantId> — the exposure itself. The exp- prefix is matched literally and is case-sensitive: EXP-7 and exp_7 are silently ignored. Repeat the parameter with different experiment ids to report several experiments in one call.
• websiteId — include it for consistency with the other endpoints and for readable logs. On this endpoint it is not read; the variant id alone determines what is counted.

What to send, and when

Send one request at the moment of exposure — when the visitor genuinely reached the thing being tested. Not on page load if the tested element is further down a funnel, and not once per request if a visitor makes several.

You own deduplication. There is no idempotency key and no visitor identity in the request, so a repeat call is a second exposure. The browser runtime deduplicates with a permanent per-experiment flag in local storage, counting each visitor once per experiment for good; mirror that with a durable visitor id plus experiment id.

Failure modes to know about

This endpoint is deliberately forgiving so that tracking can never break a customer’s site. The cost is that mistakes are silent, so they are worth listing:

• A non-numeric variant id becomes variant 0, which matches nothing. exp-7=abc is accepted and lost.
• A repeated parameter key keeps only the first value. exp-7=101&exp-7=102 records 101 and drops 102. One variant per experiment per call.
• The experiment must be started. Counters are created when an experiment starts, and aggregation increments existing counters. Exposures for a Draft experiment vanish from the running total.
• The response tells you nothing about storage. The success response is returned before the write is attempted, and failures are logged server-side only.
• No backdating. Exposures are stamped on arrival, so a queued batch lands in the hour it was flushed rather than the hour it happened.

Verifying

A bare call with no exp- parameters is a safe connectivity test: it returns a success response and records nothing.

To confirm real exposures are landing, send a few and watch the variant’s session count on the experiment’s Statistics tab. Aggregation runs every minute, so allow a short delay before concluding something is wrong.

Notes

• This endpoint counts exposures per variant. It has nothing to do with site-wide traffic; for that see the sessions endpoint.
• The variant id is the same one used in experimentVariantMap when posting conversion events.
• Exposures and conversions must use a consistent mapping, or the reported rates will be wrong.