Stop a holdout test
Stops the site's running holdout test: every session is offered the assistant again from its next page view, and the figures stay readable with `GET /holdout`. A test stopped before both groups reached the floor has no verdict; one stopped after keeps the verdict it had. `holdout_not_running` when no test runs. Records an audit entry (`site.holdout_stopped`) attributed to the API key.
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Path Parameters
The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
No field: the split is always 50/50, so a body that names a share or anything else is refused with 400.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/api/v1/sites/string/holdout/stop" \ -H "Content-Type: application/json" \ -d '{}'{ "data": { "id": "hold_01kvnwmagvf27rc9cze5rm9e1r", "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r", "status": "ended", "state": "stopped", "endedReason": "merchant_stopped", "startedAt": "2026-10-22T08:00:00.000Z", "endedAt": "2026-10-23T10:00:00.000Z", "controlPercent": 50, "trafficFloor": 5000, "control": { "assignedSessions": 1800, "convertedSessions": 140, "rate": 0.0778, "addToCartEvents": 490, "eventsWithoutAmount": 0, "valueAdded": [], "valuePerAssignedSession": [] }, "treatment": { "assignedSessions": 1760, "convertedSessions": 151, "rate": 0.0858, "addToCartEvents": 528, "eventsWithoutAmount": 0, "valueAdded": [], "valuePerAssignedSession": [] }, "progress": 0.352, "effectPoints": null, "winner": null, "detectionLimitPoints": null, "lastStorefrontAddAt": "2026-10-26T09:41:00.000Z", "plannedEndAt": "2026-11-05T08:00:00.000Z", "forecastGapPoints": null, "earlyResult": false, "engagementShare": null, "effectPerEngagedPoints": null }}Start a holdout test
Starts a holdout test on the site: from now on half of its sessions, chosen by session, are served no assistant, until the planned end, when every session is offered the assistant again. The split is always 50/50 and a body that names a share is refused with `400`. `durationDays` is the planned duration, 3, 7, 14 or 28; without it the recommendation of `GET /holdout/start-options` is used, else 14. Exposure counts in reports drop by the same share while the test runs, and a conversation in progress can lose the assistant at its next page view. The storefront must not open the assistant from its own code (`iadvize('open')` or a `data-iadvize-open` attribute): confirm it with the merchant before calling. A test starts only when the site's add-to-cart counting is on and the Shopify pixel recorded a storefront add-to-cart in the last 7 days (`holdout_measurement_unavailable` otherwise), when no widget experiment runs on the site (`holdout_experiment_running`), and a second one cannot start while one runs (`holdout_already_running`). Records an audit entry (`site.holdout_started`) attributed to the API key.
Extend a holdout test
Extends the site's running holdout test by 7, 14 or 28 days: its planned end moves later and its identity stays, so the sessions already assigned keep their group and the group without the assistant stays without it until the new end. `holdout_not_extendable` once the test has ended, reached its planned end, or when it has no planned end (it was started before planned ends existed): start a new test instead. Records an audit entry (`site.holdout_extended`) attributed to the API key.