Skip to content

A/B tests API ​

Experiments the tracker applies on customers' sites (public `GET /x/{key}` at the server root). Exposures and goals are measured from the recordings.

All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.

MethodPathWhat it does
GET/sites/{site}/experimentsThe site's A/B tests, newest first
POST/sites/{site}/experimentsCreates an A/B test (recordings:write); a draft unless status says otherwise
GET/sites/{site}/experiments/{experiment}One A/B test
PATCH/sites/{site}/experiments/{experiment}Changes an A/B test (recordings:write); variants are locked once it has started (422)
DELETE/sites/{site}/experiments/{experiment}Deletes an A/B test and its measurements (recordings:write)
GET/sites/{site}/experiments/{experiment}/resultsPer goal and variant — sessions, conversions, total hits, rate, lift, confidence — and the winner

GET /sites/{site}/experiments ​

The site's A/B tests, newest first

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
archivedquerybooleanWith 1: only archived tests (else only the others).

Responses ​

  • 200 — Experiments.
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject[]
data[].idinteger
data[].site_idinteger
data[].namestring
data[].statusstringOne of: draft, running, stopped.
data[].pageobject
data[].trafficinteger
data[].variantsobject[]
data[].variants[].idstring
data[].variants[].namestring
data[].variants[].changesobject[]
data[].goalsobject[]
data[].goals[].typestringyesOne of: page, click, event, engagement, tag.
data[].goals[].namestring, nullableAt most 60 characters.
data[].goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
data[].goals[].valuestring, nullable
data[].goals[].keystring
data[].goals[].selectorstring, nullable
data[].goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data[].goal.typestringyesOne of: page, click, event, engagement, tag.
data[].goal.namestring, nullableAt most 60 characters.
data[].goal.opstringOne of: is, contains, begins, pattern, regex, not_regex.
data[].goal.valuestring, nullable
data[].goal.keystring
data[].goal.selectorstring, nullable
data[].activationstringOne of: auto, manual.
data[].archived_atstring (date-time), nullable
data[].started_atstring (date-time), nullable
data[].created_atstring (date-time), nullable
data[].updated_atstring (date-time), nullable
metaobject
meta.scripts_allowedboolean
meta.visitorsobjectThis month's A/B test visitors against the plan limit experiments.visitors_monthly (limit null = unlimited); once reached, the tracker gets no tests until next month.
meta.visitors.usedinteger
meta.visitors.limitinteger, nullable
meta.visitors.reachedboolean
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/experiments" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /sites/{site}/experiments ​

Creates an A/B test (recordings:write); a draft unless status says otherwise

403 when the account's plan allows no more tests (plan feature experiments.count).

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringyesAt most 120 characters.
statusstringOne of: draft, running, stopped.
activationstringmanual: runs only after the page calls __sr.push(['activateExperiment', id]). One of: auto, manual. Default "auto".
archivedbooleanPATCH only: archive (stops a running test, hides it from the list) or bring back.
pageobjectyes
page.opstringOne of: any, is, contains, begins, pattern, regex, not_regex.
page.valuestring, nullable
trafficinteger% of visitors in the test, split evenly over the variants. Minimum 1. Maximum 100. Default 100.
variantsobject[]yesThe first is the original page (no changes); ids a–d are given in order. At most 4 items.
variants[].namestring
variants[].changesobject[]At most 20 items.
variants[].changes[].actionstringyesOne of: text, hide, style, attribute, move, redirect, script.
variants[].changes[].selectorstringCSS selector of the elements to change (all actions but redirect and script).
variants[].changes[].valuestring, nullableNew text, CSS declarations, attribute value, (move) the CSS selector of the element to move next to, the http(s) address to redirect to, or (script) JavaScript run once on the page — only when the server allows custom code (meta.scripts_allowed of the list) and for account managers.
variants[].changes[].namestring, nullableAttribute name (no on* handlers, no style/srcdoc; href/src must be http(s) or relative); for move: before or after.
goalsobject[]yesThe first is the primary one (it decides the winner). Once a test has run, goals can only be renamed or new ones added at the end (422). A single goal object is accepted instead. At most 5 items.
goals[].typestringyesOne of: page, click, event, engagement, tag.
goals[].namestring, nullableAt most 60 characters.
goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
goals[].valuestring, nullable
goals[].keystring
goals[].selectorstring, nullable

Responses ​

  • 201 — Created.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 404 — Missing, or another account's.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.site_idinteger
data.namestring
data.statusstringOne of: draft, running, stopped.
data.pageobject
data.trafficinteger
data.variantsobject[]
data.variants[].idstring
data.variants[].namestring
data.variants[].changesobject[]
data.goalsobject[]
data.goals[].typestringyesOne of: page, click, event, engagement, tag.
data.goals[].namestring, nullableAt most 60 characters.
data.goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goals[].valuestring, nullable
data.goals[].keystring
data.goals[].selectorstring, nullable
data.goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data.goal.typestringyesOne of: page, click, event, engagement, tag.
data.goal.namestring, nullableAt most 60 characters.
data.goal.opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goal.valuestring, nullable
data.goal.keystring
data.goal.selectorstring, nullable
data.activationstringOne of: auto, manual.
data.archived_atstring (date-time), nullable
data.started_atstring (date-time), nullable
data.created_atstring (date-time), nullable
data.updated_atstring (date-time), nullable
bash
curl -X POST "https://your-site.com/api/v1/sites/{site}/experiments" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","status":"draft","activation":"auto","archived":true,"page":{"op":"any","value":"text"},"traffic":100,"variants":[{"name":"text","changes":[]}],"goals":[{"type":"page"}]}'

GET /sites/{site}/experiments/{experiment} ​

One A/B test

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
experimentpathintegeryes

Responses ​

  • 200 — The experiment.
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.site_idinteger
data.namestring
data.statusstringOne of: draft, running, stopped.
data.pageobject
data.trafficinteger
data.variantsobject[]
data.variants[].idstring
data.variants[].namestring
data.variants[].changesobject[]
data.goalsobject[]
data.goals[].typestringyesOne of: page, click, event, engagement, tag.
data.goals[].namestring, nullableAt most 60 characters.
data.goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goals[].valuestring, nullable
data.goals[].keystring
data.goals[].selectorstring, nullable
data.goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data.goal.typestringyesOne of: page, click, event, engagement, tag.
data.goal.namestring, nullableAt most 60 characters.
data.goal.opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goal.valuestring, nullable
data.goal.keystring
data.goal.selectorstring, nullable
data.activationstringOne of: auto, manual.
data.archived_atstring (date-time), nullable
data.started_atstring (date-time), nullable
data.created_atstring (date-time), nullable
data.updated_atstring (date-time), nullable
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/experiments/{experiment}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

PATCH /sites/{site}/experiments/{experiment} ​

Changes an A/B test (recordings:write); variants are locked once it has started (422)

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
experimentpathintegeryes

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringyesAt most 120 characters.
statusstringOne of: draft, running, stopped.
activationstringmanual: runs only after the page calls __sr.push(['activateExperiment', id]). One of: auto, manual. Default "auto".
archivedbooleanPATCH only: archive (stops a running test, hides it from the list) or bring back.
pageobjectyes
page.opstringOne of: any, is, contains, begins, pattern, regex, not_regex.
page.valuestring, nullable
trafficinteger% of visitors in the test, split evenly over the variants. Minimum 1. Maximum 100. Default 100.
variantsobject[]yesThe first is the original page (no changes); ids a–d are given in order. At most 4 items.
variants[].namestring
variants[].changesobject[]At most 20 items.
variants[].changes[].actionstringyesOne of: text, hide, style, attribute, move, redirect, script.
variants[].changes[].selectorstringCSS selector of the elements to change (all actions but redirect and script).
variants[].changes[].valuestring, nullableNew text, CSS declarations, attribute value, (move) the CSS selector of the element to move next to, the http(s) address to redirect to, or (script) JavaScript run once on the page — only when the server allows custom code (meta.scripts_allowed of the list) and for account managers.
variants[].changes[].namestring, nullableAttribute name (no on* handlers, no style/srcdoc; href/src must be http(s) or relative); for move: before or after.
goalsobject[]yesThe first is the primary one (it decides the winner). Once a test has run, goals can only be renamed or new ones added at the end (422). A single goal object is accepted instead. At most 5 items.
goals[].typestringyesOne of: page, click, event, engagement, tag.
goals[].namestring, nullableAt most 60 characters.
goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
goals[].valuestring, nullable
goals[].keystring
goals[].selectorstring, nullable

Responses ​

  • 200 — The experiment.
  • 404 — Missing, or another account's.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.site_idinteger
data.namestring
data.statusstringOne of: draft, running, stopped.
data.pageobject
data.trafficinteger
data.variantsobject[]
data.variants[].idstring
data.variants[].namestring
data.variants[].changesobject[]
data.goalsobject[]
data.goals[].typestringyesOne of: page, click, event, engagement, tag.
data.goals[].namestring, nullableAt most 60 characters.
data.goals[].opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goals[].valuestring, nullable
data.goals[].keystring
data.goals[].selectorstring, nullable
data.goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data.goal.typestringyesOne of: page, click, event, engagement, tag.
data.goal.namestring, nullableAt most 60 characters.
data.goal.opstringOne of: is, contains, begins, pattern, regex, not_regex.
data.goal.valuestring, nullable
data.goal.keystring
data.goal.selectorstring, nullable
data.activationstringOne of: auto, manual.
data.archived_atstring (date-time), nullable
data.started_atstring (date-time), nullable
data.created_atstring (date-time), nullable
data.updated_atstring (date-time), nullable
bash
curl -X PATCH "https://your-site.com/api/v1/sites/{site}/experiments/{experiment}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","status":"draft","activation":"auto","archived":true,"page":{"op":"any","value":"text"},"traffic":100,"variants":[{"name":"text","changes":[]}],"goals":[{"type":"page"}]}'

DELETE /sites/{site}/experiments/{experiment} ​

Deletes an A/B test and its measurements (recordings:write)

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
experimentpathintegeryes

Responses ​

  • 204 — Deleted.
  • 404 — Missing, or another account's.
bash
curl -X DELETE "https://your-site.com/api/v1/sites/{site}/experiments/{experiment}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

GET /sites/{site}/experiments/{experiment}/results ​

Per goal and variant — sessions, conversions, total hits, rate, lift, confidence — and the winner

Per goal (goals, the first is the primary one; variants repeats its rows): conversions are sessions that reached the goal after seeing the variant, hits every page view, click or event of the goal in total. lift is the change of the conversion rate over the original (a), in %; confidence is how sure a two-sided two-proportion z-test is that the rate differs from the original (null below 30 sessions per side or without conversions); needed is about how many more sessions per variant a difference of the size seen would need to be significant (95% confidence, 80% power; null when it can't be told yet). winner: the best variant significantly better than the original (95%), a when every variant is significantly worse, else null.

Parameters ​

NameInTypeRequiredDescription
sitepathintegeryes
experimentpathintegeryes
devicequerystringOne of: desktop, mobile, tablet.
sourcequerystringOne of: direct, search, social, email, paid, referral.
visitorquerystringOne of: new, returning.

Responses ​

  • 200 — The results.
  • 404 — Missing, or another account's.
Response fields
FieldTypeRequiredDescription
dataobject
data.experimentobject
data.experiment.idinteger
data.experiment.site_idinteger
data.experiment.namestring
data.experiment.statusstringOne of: draft, running, stopped.
data.experiment.pageobject
data.experiment.trafficinteger
data.experiment.variantsobject[]
data.experiment.goalsobject[]
data.experiment.goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data.experiment.activationstringOne of: auto, manual.
data.experiment.archived_atstring (date-time), nullable
data.experiment.started_atstring (date-time), nullable
data.experiment.created_atstring (date-time), nullable
data.experiment.updated_atstring (date-time), nullable
data.sessionsinteger
data.goalsobject[]
data.goals[].indexinteger
data.goals[].goalobjectpage: {op, value} — a page view; click: {value} (text of the clicked element contains) or {selector} (the click is inside the element; checked by the tracker); event: {value} — __sr.push(['event', value]); engagement: {} — any click; tag: {key, value?} — a session tag. Each may have a name.
data.goals[].winnerstring, nullable
data.goals[].significantboolean
data.goals[].variantsobject[]
data.variantsobject[]
data.variants[].idstring
data.variants[].namestring
data.variants[].sessionsinteger
data.variants[].conversionsinteger
data.variants[].hitsinteger
data.variants[].ratenumber
data.variants[].neededinteger, nullable
data.variants[].liftnumber, nullable
data.variants[].confidencenumber, nullable
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/experiments/{experiment}/results" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

Replora: see what your visitors see.