Appearance
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.
| Method | Path | What it does |
|---|---|---|
| GET | /sites/{site}/experiments | The site's A/B tests, newest first |
| POST | /sites/{site}/experiments | Creates 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}/results | Per 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
archived | query | boolean | With 1: only archived tests (else only the others). |
Responses
- 200 — Experiments.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].site_id | integer | ||
data[].name | string | ||
data[].status | string | One of: draft, running, stopped. | |
data[].page | object | ||
data[].traffic | integer | ||
data[].variants | object[] | ||
data[].variants[].id | string | ||
data[].variants[].name | string | ||
data[].variants[].changes | object[] | ||
data[].goals | object[] | ||
data[].goals[].type | string | yes | One of: page, click, event, engagement, tag. |
data[].goals[].name | string, nullable | At most 60 characters. | |
data[].goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data[].goals[].value | string, nullable | ||
data[].goals[].key | string | ||
data[].goals[].selector | string, nullable | ||
data[].goal | object | page: {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.type | string | yes | One of: page, click, event, engagement, tag. |
data[].goal.name | string, nullable | At most 60 characters. | |
data[].goal.op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data[].goal.value | string, nullable | ||
data[].goal.key | string | ||
data[].goal.selector | string, nullable | ||
data[].activation | string | One of: auto, manual. | |
data[].archived_at | string (date-time), nullable | ||
data[].started_at | string (date-time), nullable | ||
data[].created_at | string (date-time), nullable | ||
data[].updated_at | string (date-time), nullable | ||
meta | object | ||
meta.scripts_allowed | boolean | ||
meta.visitors | object | This 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.used | integer | ||
meta.visitors.limit | integer, nullable | ||
meta.visitors.reached | boolean |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | At most 120 characters. |
status | string | One of: draft, running, stopped. | |
activation | string | manual: runs only after the page calls __sr.push(['activateExperiment', id]). One of: auto, manual. Default "auto". | |
archived | boolean | PATCH only: archive (stops a running test, hides it from the list) or bring back. | |
page | object | yes | |
page.op | string | One of: any, is, contains, begins, pattern, regex, not_regex. | |
page.value | string, nullable | ||
traffic | integer | % of visitors in the test, split evenly over the variants. Minimum 1. Maximum 100. Default 100. | |
variants | object[] | yes | The first is the original page (no changes); ids a–d are given in order. At most 4 items. |
variants[].name | string | ||
variants[].changes | object[] | At most 20 items. | |
variants[].changes[].action | string | yes | One of: text, hide, style, attribute, move, redirect, script. |
variants[].changes[].selector | string | CSS selector of the elements to change (all actions but redirect and script). | |
variants[].changes[].value | string, nullable | New 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[].name | string, nullable | Attribute name (no on* handlers, no style/srcdoc; href/src must be http(s) or relative); for move: before or after. | |
goals | object[] | yes | The 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[].type | string | yes | One of: page, click, event, engagement, tag. |
goals[].name | string, nullable | At most 60 characters. | |
goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
goals[].value | string, nullable | ||
goals[].key | string | ||
goals[].selector | string, 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
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.status | string | One of: draft, running, stopped. | |
data.page | object | ||
data.traffic | integer | ||
data.variants | object[] | ||
data.variants[].id | string | ||
data.variants[].name | string | ||
data.variants[].changes | object[] | ||
data.goals | object[] | ||
data.goals[].type | string | yes | One of: page, click, event, engagement, tag. |
data.goals[].name | string, nullable | At most 60 characters. | |
data.goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goals[].value | string, nullable | ||
data.goals[].key | string | ||
data.goals[].selector | string, nullable | ||
data.goal | object | page: {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.type | string | yes | One of: page, click, event, engagement, tag. |
data.goal.name | string, nullable | At most 60 characters. | |
data.goal.op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goal.value | string, nullable | ||
data.goal.key | string | ||
data.goal.selector | string, nullable | ||
data.activation | string | One of: auto, manual. | |
data.archived_at | string (date-time), nullable | ||
data.started_at | string (date-time), nullable | ||
data.created_at | string (date-time), nullable | ||
data.updated_at | string (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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
experiment | path | integer | yes |
Responses
- 200 — The experiment.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.status | string | One of: draft, running, stopped. | |
data.page | object | ||
data.traffic | integer | ||
data.variants | object[] | ||
data.variants[].id | string | ||
data.variants[].name | string | ||
data.variants[].changes | object[] | ||
data.goals | object[] | ||
data.goals[].type | string | yes | One of: page, click, event, engagement, tag. |
data.goals[].name | string, nullable | At most 60 characters. | |
data.goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goals[].value | string, nullable | ||
data.goals[].key | string | ||
data.goals[].selector | string, nullable | ||
data.goal | object | page: {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.type | string | yes | One of: page, click, event, engagement, tag. |
data.goal.name | string, nullable | At most 60 characters. | |
data.goal.op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goal.value | string, nullable | ||
data.goal.key | string | ||
data.goal.selector | string, nullable | ||
data.activation | string | One of: auto, manual. | |
data.archived_at | string (date-time), nullable | ||
data.started_at | string (date-time), nullable | ||
data.created_at | string (date-time), nullable | ||
data.updated_at | string (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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
experiment | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | At most 120 characters. |
status | string | One of: draft, running, stopped. | |
activation | string | manual: runs only after the page calls __sr.push(['activateExperiment', id]). One of: auto, manual. Default "auto". | |
archived | boolean | PATCH only: archive (stops a running test, hides it from the list) or bring back. | |
page | object | yes | |
page.op | string | One of: any, is, contains, begins, pattern, regex, not_regex. | |
page.value | string, nullable | ||
traffic | integer | % of visitors in the test, split evenly over the variants. Minimum 1. Maximum 100. Default 100. | |
variants | object[] | yes | The first is the original page (no changes); ids a–d are given in order. At most 4 items. |
variants[].name | string | ||
variants[].changes | object[] | At most 20 items. | |
variants[].changes[].action | string | yes | One of: text, hide, style, attribute, move, redirect, script. |
variants[].changes[].selector | string | CSS selector of the elements to change (all actions but redirect and script). | |
variants[].changes[].value | string, nullable | New 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[].name | string, nullable | Attribute name (no on* handlers, no style/srcdoc; href/src must be http(s) or relative); for move: before or after. | |
goals | object[] | yes | The 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[].type | string | yes | One of: page, click, event, engagement, tag. |
goals[].name | string, nullable | At most 60 characters. | |
goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
goals[].value | string, nullable | ||
goals[].key | string | ||
goals[].selector | string, nullable |
Responses
- 200 — The experiment.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.status | string | One of: draft, running, stopped. | |
data.page | object | ||
data.traffic | integer | ||
data.variants | object[] | ||
data.variants[].id | string | ||
data.variants[].name | string | ||
data.variants[].changes | object[] | ||
data.goals | object[] | ||
data.goals[].type | string | yes | One of: page, click, event, engagement, tag. |
data.goals[].name | string, nullable | At most 60 characters. | |
data.goals[].op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goals[].value | string, nullable | ||
data.goals[].key | string | ||
data.goals[].selector | string, nullable | ||
data.goal | object | page: {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.type | string | yes | One of: page, click, event, engagement, tag. |
data.goal.name | string, nullable | At most 60 characters. | |
data.goal.op | string | One of: is, contains, begins, pattern, regex, not_regex. | |
data.goal.value | string, nullable | ||
data.goal.key | string | ||
data.goal.selector | string, nullable | ||
data.activation | string | One of: auto, manual. | |
data.archived_at | string (date-time), nullable | ||
data.started_at | string (date-time), nullable | ||
data.created_at | string (date-time), nullable | ||
data.updated_at | string (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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
experiment | path | integer | yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
experiment | path | integer | yes | |
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — The results.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.experiment | object | ||
data.experiment.id | integer | ||
data.experiment.site_id | integer | ||
data.experiment.name | string | ||
data.experiment.status | string | One of: draft, running, stopped. | |
data.experiment.page | object | ||
data.experiment.traffic | integer | ||
data.experiment.variants | object[] | ||
data.experiment.goals | object[] | ||
data.experiment.goal | object | page: {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.activation | string | One of: auto, manual. | |
data.experiment.archived_at | string (date-time), nullable | ||
data.experiment.started_at | string (date-time), nullable | ||
data.experiment.created_at | string (date-time), nullable | ||
data.experiment.updated_at | string (date-time), nullable | ||
data.sessions | integer | ||
data.goals | object[] | ||
data.goals[].index | integer | ||
data.goals[].goal | object | page: {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[].winner | string, nullable | ||
data.goals[].significant | boolean | ||
data.goals[].variants | object[] | ||
data.variants | object[] | ||
data.variants[].id | string | ||
data.variants[].name | string | ||
data.variants[].sessions | integer | ||
data.variants[].conversions | integer | ||
data.variants[].hits | integer | ||
data.variants[].rate | number | ||
data.variants[].needed | integer, nullable | ||
data.variants[].lift | number, nullable | ||
data.variants[].confidence | number, 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"