> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/split-testing-api.md).

# Split Testing API

The Split Testing API lets you programmatically get AI-powered A/B test recommendations and create split tests (no-code visual tests and redirect tests) from an AI coding agent or HTTP client. It supports growth teams and agencies that want agent assistance inside a human-reviewed CRO workflow.

> **Base URL**: `https://app.humblytics.com/api/external/v1`

> **New to split testing?** Read the [Split Testing Overview](https://docs.humblytics.com/split-testing-overview.md) for conceptual background on how Humblytics A/B testing works, goal types, and statistical methodology before diving into the API.

> **Looking for analytics endpoints?** The [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) covers traffic, pages, clicks, forms, and funnels data — useful for monitoring experiment performance alongside these split testing endpoints.

> **Using an AI agent?** Connect it over MCP from the **Agents** page instead of calling these endpoints by hand: the MCP server exposes the same operations as tools, including in-chat approval. See [MCP & API Access](https://docs.humblytics.com/api-access-and-agents.md).

***

## Use Cases

### Automated CRO with AI Agents

The Split Testing API is designed to work hand-in-hand with AI coding agents. Here are the primary use cases:

| Use Case                         | How It Works                                                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **AI-driven test ideation**      | Your agent calls the recommendations endpoint, receives data-backed suggestions (selectors, copy, CSS changes), and presents them for review. |
| **Reviewed experiment creation** | After a person reviews and approves a recommendation, the agent can create the split test via the API.                                        |
| **Monitored optimization loops** | An agent can periodically fetch recommendations and monitor results while the team retains approval over what is launched.                    |
| **Multi-page audit**             | The agent iterates over your top landing pages, fetches recommendations for each, and builds a prioritized optimization backlog.              |

***

## Authentication

Uses the same API keys as the External Analytics API. Account keys (recommended) work for every site you own; property keys only for their own site.

```http
Authorization: Bearer <your_api_key>
```

See [External Analytics API — Authentication](https://docs.humblytics.com/external-analytics-api.md#authentication) for key generation and management details.

***

## Get Split Test Recommendations

```
GET /properties/{propertyId}/split-test-recommendations
```

Returns AI-generated A/B test recommendations for a specific page, based on your existing analytics data (traffic patterns, click behavior, bounce rates, and more). Each recommendation includes the exact CSS selector, change type, control value, and suggested variant value — ready to feed directly into the split test creation endpoint.

### Query Parameters

| Name   | Type   | Required | Default | Notes                                                                |
| ------ | ------ | -------- | ------- | -------------------------------------------------------------------- |
| `page` | string | Yes      | N/A     | The page path to get recommendations for (e.g. `/home`, `/pricing`). |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-test-recommendations?page=/home"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "prop_abc123",
    "page": "/home",
    "page_url": "https://yoursite.com/home"
  },
  "overall_analysis": "Your hero section has high traffic but a 78% bounce rate. The primary CTA is underperforming relative to page views, suggesting copy and visual prominence changes could yield significant gains.",
  "key_insights": [
    "CTA button receives only 3% of clicks despite above-the-fold placement",
    "Users spend an average of 4.2 seconds on the hero section before scrolling",
    "Mobile bounce rate is 12% higher than desktop on this page"
  ],
  "recommendations": [
    {
      "id": "rec_1",
      "title": "Hero CTA Text",
      "element_selector": "button.hero-cta",
      "element_type": "button",
      "change_type": "text",
      "control_value": "Learn More",
      "variant_value": "Start Free Trial",
      "confidence_score": 84,
      "expected_impact": "High: 8%+"
    },
    {
      "id": "rec_2",
      "title": "Hero CTA Color",
      "element_selector": "button.hero-cta",
      "element_type": "button",
      "change_type": "css",
      "control_value": "{ \"backgroundColor\": \"#6b7280\" }",
      "variant_value": "{ \"backgroundColor\": \"#ff6b35\" }",
      "confidence_score": 71,
      "expected_impact": "Medium: 3-8%"
    }
  ]
}
```

### Response Fields

| Field                                | Description                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `overall_analysis`                   | A human-readable summary of the page's performance and optimization opportunities.           |
| `key_insights`                       | Array of specific data-backed observations about user behavior on the page.                  |
| `recommendations[].id`               | Unique recommendation ID (useful for logging and tracking).                                  |
| `recommendations[].element_selector` | CSS selector for the target element — use this directly in the split test creation endpoint. |
| `recommendations[].element_type`     | The type of HTML element (e.g. `button`, `heading`, `image`).                                |
| `recommendations[].change_type`      | The kind of change: `text` (copy change) or `css` (style change).                            |
| `recommendations[].control_value`    | The current value on your live page.                                                         |
| `recommendations[].variant_value`    | The suggested new value to test against the control.                                         |
| `recommendations[].confidence_score` | 0–100 score indicating how confident the AI is that this change will improve performance.    |
| `recommendations[].expected_impact`  | Estimated impact level: `Low: <3%`, `Medium: 3-8%`, or `High: 8%+`.                          |

### Notes

* Recommendations are generated from your actual analytics data — they are not generic suggestions.
* Higher `confidence_score` values indicate stronger data signals behind the recommendation.
* The `element_selector` and `change_type` fields map directly to the `selector` and `op` fields in the split test creation endpoint, making it easy to pipe recommendations into live experiments.
* This is the one rate-limited endpoint. Over the limit it answers `429` with a flat body: `{ "error": "rate_limit_exceeded", "reason", "usage", "limits" }`. `503 service_unavailable` means the AI service is not available right now; `503 subscription_status_unavailable` means retry shortly.

***

## Preview a Change

```
POST /properties/{propertyId}/split-test-preview
```

Captures a **before** screenshot of a page and an **after** screenshot with your changes applied, so a reviewer can see a variant before the test exists. Nothing is saved.

### Request Body

| Field          | Type   | Required | Notes                                                                                   |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `pageUrl`      | string | Yes      | Full URL of the page (e.g. `https://yoursite.com/home`).                                |
| `instructions` | array  | Yes      | One or more change objects (`selector`, `op`, `value`) as used in `variants[].changes`. |

### Sample Request

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pageUrl": "https://yoursite.com/home",
    "instructions": [{ "selector": "button.hero-cta", "op": "text", "value": "Start Free Trial" }]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-test-preview"
```

### Sample Response

```json
{
  "beforeUrl": "https://…/before.png",
  "afterUrl": "https://…/after.png",
  "verificationResults": [
    { "selector": "button.hero-cta", "op": "text", "applied": true }
  ]
}
```

`503 service_unavailable` when the screenshot service is not available.

***

## Create a Split Test

```
POST /properties/{propertyId}/split-tests
```

Creates an A/B split test that **awaits a person's approval**. The test is saved with `status: "draft"` and is not served to any visitor until someone activates it (see [Approval](#approval-of-agent-created-tests)). Two test types are supported:

* **`nocode`** — Visual/DOM test. The Humblytics script injects element-level changes (text swaps, CSS overrides, HTML replacements, image swaps, element deletions, or duplications) at runtime — no code deployment required.
* **`redirect`** — Redirect test. Visitors are sent to entirely different page URLs instead of seeing DOM changes on the same page.

### Request Body

| Field            | Type   | Required | Default | Notes                                                                                                                                                                                                   |
| ---------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | string | Yes      | N/A     | A descriptive name for the experiment (up to 100 characters).                                                                                                                                           |
| `page`           | string | Yes      | N/A     | The page path to run the test on (e.g. `/home`).                                                                                                                                                        |
| `type`           | string | Yes      | N/A     | `nocode` for visual/DOM tests, `redirect` for redirect tests.                                                                                                                                           |
| `goal`           | string | No       | N/A     | The optimization goal. See goal options below.                                                                                                                                                          |
| `auto_stop_days` | number | No       | `30`    | Stop the test automatically after this many days (1–30). Pass `0` to never auto-stop.                                                                                                                   |
| `variants`       | array  | Yes      | N/A     | 1–3 variant definitions (see below).                                                                                                                                                                    |
| `draft_id`       | string | No       | N/A     | Start a test drafted by the Humblytics website audit. With `draft_id` you may omit `name`, `page`, `type` and `variants`: Humblytics finds the drafted copy on the audited page and builds the variant. |

**Goal Options**

| Value                  | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `click_through_rate`   | Optimize for click-through rate on the page.    |
| `form_submissions`     | Optimize for form submission rate.              |
| `bounce_rate`          | Optimize for reduced bounce rate.               |
| `session_time`         | Optimize for increased session duration.        |
| `page_funnel`          | Optimize for visitors reaching a specific page. |
| `external_page_funnel` | Optimize for visitors reaching an external URL. |
| `revenue`              | Optimize for revenue per visitor.               |

### No-Code Variant Object (`type: "nocode"`)

| Field     | Type   | Required | Notes                                                               |
| --------- | ------ | -------- | ------------------------------------------------------------------- |
| `label`   | string | No       | A descriptive label for this variant (e.g. `Variant B — new copy`). |
| `changes` | array  | Yes      | One or more changes to apply. See below.                            |

**Change Object**

| Field      | Type             | Required | Notes                                                                                                                                                                                                         |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selector` | string           | Yes      | CSS selector for the target element.                                                                                                                                                                          |
| `op`       | string           | Yes      | The operation: `text` (replace text content), `css` (apply CSS styles), `html` (replace inner HTML), `image` (swap image source), `delete` (remove element), or `duplicate` (clone element).                  |
| `value`    | string or object | Yes      | The new value. For `css`, pass a JSON object of CSS properties. For `text`, `html`, and `image`, pass a string. For `delete` and `duplicate`, the value is ignored but still required (pass an empty string). |

### Redirect Variant Object (`type: "redirect"`)

| Field   | Type   | Required | Notes                                                                                               |
| ------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `label` | string | No       | A descriptive label for this variant.                                                               |
| `url`   | string | Yes      | The path to redirect to (e.g. `"/home-v2"`). Must differ from `page` and be unique across variants. |

### Sample Request — No-Code Test

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero CTA Optimization",
    "page": "/home",
    "type": "nocode",
    "goal": "click_through_rate",
    "auto_stop_days": 14,
    "variants": [
      {
        "label": "Variant B — new copy + color",
        "changes": [
          {
            "selector": "button.hero-cta",
            "op": "text",
            "value": "Start Free Trial"
          },
          {
            "selector": "button.hero-cta",
            "op": "css",
            "value": { "backgroundColor": "#ff6b35" }
          }
        ]
      }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests"
```

### Sample Request — Redirect Test

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage Redesign Test",
    "page": "/home",
    "type": "redirect",
    "goal": "form_submissions",
    "auto_stop_days": 14,
    "variants": [
      {
        "label": "Redesigned Homepage",
        "url": "/home-v2"
      }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests"
```

### Sample Response (201 Created)

```json
{
  "experiment_id": "0c1f8f0e-…",
  "approval_url": "https://app.humblytics.com/p/PROPERTY_ID/split-tests/0c1f8f0e-…",
  "auto_stop_days": 14,
  "name": "Hero CTA Optimization",
  "status": "draft",
  "type": "component_a_b",
  "kind": "nocode",
  "created_at": "2026-03-27T10:00:00.000Z",
  "variants": [
    {
      "label": "Control",
      "is_control": true,
      "changes": []
    },
    {
      "label": "Variant B — new copy + color",
      "is_control": false,
      "changes": [
        { "selector": "button.hero-cta", "op": "text", "value": "Start Free Trial" },
        { "selector": "button.hero-cta", "op": "css", "value": { "backgroundColor": "#ff6b35" } }
      ]
    }
  ]
}
```

### Notes

* A **Control** variant is automatically created — you only need to define the variants you want to test against it.
* The test is created as a **draft**. Give the person the `approval_url` (or use in-chat approval over MCP) — visitors are only assigned once it is activated.
* `type` is the stored experiment type (`component_a_b` for no-code, `a_b` for redirect); `kind` is the request shape, `nocode` or `redirect`. Redirect variants also carry their `url`.
* **No-code tests**: Changes are applied at runtime by the Humblytics script. No code changes or redeployments are needed on your site. You can combine multiple changes per variant (e.g. text + CSS on the same element, or changes across multiple elements).
* **Redirect tests**: Each variant's `url` must differ from the `page` and be unique across variants. The Humblytics script handles the redirect transparently.
* `auto_stop_days` defaults to 30. Pass `0` if the test should run until it is stopped by hand.
* Limits: a site can hold at most 10 drafts waiting for approval (`409 too_many_drafts` — activate or stop one first), and activating a test takes an active-test slot on your plan (`402` with a flat `{ "error": "plan_limit_reached", "limit", "current" }` body).
* With `draft_id`: `404 not_found` when the drafted test is not on this site, `409 draft_already_started` when it is already running or starting, and `422` with `copy_not_found_on_page`, `page_unreachable` or `audit_page_not_on_site` when Humblytics could not place the drafted copy on the page — send `page` and `variants` with a selector instead.

***

## Activate a Split Test (MCP only)

```
POST /properties/{propertyId}/split-tests/{experimentId}/activate
```

Puts a draft in front of real visitors. This is the approval step the Humblytics MCP server performs after the person confirms in their chat client; it needs the API key **and** an `X-Humblytics-Approval` header carrying a secret only the MCP server holds, so an agent calling the API on its own cannot launch a test. Use the `activate_split_test` MCP tool, or open the `approval_url`.

Responses: the full experiment object with `status: "active"`; `403 forbidden` without the approval header; `403 launch_not_allowed` when **Launch tests** is off for this key (approve from the `approval_url`, or turn it on under **Agents → API keys**); `409 invalid_state` if the test is not a draft; `402 plan_limit_reached` when no active-test slot is free.

***

## List Split Tests

```
GET /properties/{propertyId}/split-tests
```

Returns all experiments for the property. Optionally filter by status.

### Query Parameters

| Name     | Type | Required | Default | Notes                                      |
| -------- | ---- | -------- | ------- | ------------------------------------------ |
| `status` | enum | No       | N/A     | Filter by `draft`, `active` or `complete`. |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests?status=active"
```

### Sample Response

```json
{
  "experiments": [
    {
      "experiment_id": "0c1f8f0e-…",
      "approval_url": "https://app.humblytics.com/p/PROPERTY_ID/split-tests/0c1f8f0e-…",
      "name": "Hero CTA Optimization",
      "status": "active",
      "type": "component_a_b",
      "kind": "nocode",
      "page": "/home",
      "goal": "click_through_rate",
      "created_at": "2026-03-27T10:00:00.000Z",
      "ended_at": null,
      "auto_stop_days": 14,
      "stopped_reason": null,
      "variants": [
        { "label": "Control", "is_control": true, "changes": [] },
        { "label": "Variant B — new copy + color", "is_control": false, "changes": [{ "selector": "button.hero-cta", "op": "text", "value": "Start Free Trial" }] }
      ]
    }
  ]
}
```

***

## Get Split Test Details

```
GET /properties/{propertyId}/split-tests/{experimentId}
```

Returns the same experiment object as the list, with per-variant metrics.

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests/0c1f8f0e-…"
```

### Sample Response

```json
{
  "experiment_id": "0c1f8f0e-…",
  "approval_url": "https://app.humblytics.com/p/PROPERTY_ID/split-tests/0c1f8f0e-…",
  "name": "Hero CTA Optimization",
  "status": "active",
  "type": "component_a_b",
  "kind": "nocode",
  "page": "/home",
  "goal": "click_through_rate",
  "created_at": "2026-03-27T10:00:00.000Z",
  "ended_at": null,
  "auto_stop_days": 14,
  "stopped_reason": null,
  "variants": [
    {
      "label": "Control",
      "is_control": true,
      "changes": [],
      "metrics": {
        "views": [{ "variant": "a", "count": 1523 }],
        "sessions": [{ "variant": "a", "count": 1402 }],
        "totalEvents": [{ "variant": "a", "count": 198 }],
        "timeSeriesSessions": [],
        "timeSeriesConversions": []
      }
    },
    {
      "label": "Variant B — new copy + color",
      "is_control": false,
      "changes": [
        { "selector": "button.hero-cta", "op": "text", "value": "Start Free Trial" },
        { "selector": "button.hero-cta", "op": "css", "value": { "backgroundColor": "#ff6b35" } }
      ],
      "metrics": {
        "views": [{ "variant": "b", "count": 1489 }],
        "sessions": [{ "variant": "b", "count": 1370 }],
        "totalEvents": [{ "variant": "b", "count": 247 }],
        "timeSeriesSessions": [],
        "timeSeriesConversions": []
      }
    }
  ]
}
```

### Notes

* `metrics` is the raw per-variant data behind the dashboard: `views`, `sessions`, `totalEvents` (goal events), `topEvents`, `timeSeriesSessions`, `timeSeriesConversions`, and `…ByDevice` splits, each an array of rows. Divide goal events by sessions for a conversion rate.
* A draft that never ran reports empty metrics.

***

## Update a Split Test

```
PATCH /properties/{propertyId}/split-tests/{experimentId}
```

Updates a draft or active experiment. Only the fields you include in the body are changed.

### Request Body

| Field            | Type   | Required | Notes                                              |
| ---------------- | ------ | -------- | -------------------------------------------------- |
| `name`           | string | No       | Update the experiment name (up to 100 characters). |
| `auto_stop_days` | number | No       | 1–30 days; `null` or `0` turns auto-stop off.      |

### Sample Request

```bash
curl -X PATCH \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero CTA Optimization v2",
    "auto_stop_days": 21
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests/0c1f8f0e-…"
```

### Sample Response

The full experiment object (as in the list), with the new values. `409 invalid_state` when the experiment is already complete.

***

## Stop a Split Test

```
POST /properties/{propertyId}/split-tests/{experimentId}/stop
```

Stops a running experiment, or discards a draft. Optionally include a reason.

### Request Body

| Field    | Type   | Required | Notes                                  |
| -------- | ------ | -------- | -------------------------------------- |
| `reason` | string | No       | Optional reason for stopping the test. |

### Sample Request

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Variant B is a clear winner" }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests/0c1f8f0e-…/stop"
```

### Sample Response

```json
{ "ok": true, "experiment_id": "0c1f8f0e-…" }
```

### Notes

* Once stopped, a test cannot be restarted. Create a new test if you want to continue testing.
* Stopping a draft discards it (it is archived, not listed with finished tests).
* If no reason is provided, the test is recorded as manually stopped. `409 invalid_state` when it is already complete.

***

## End-to-End Workflow: Recommendations to Live Test

The most powerful pattern is chaining both endpoints — fetch recommendations, then create a test from the highest-confidence suggestion:

### Step 1 — Get Recommendations

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-test-recommendations?page=/home"
```

Review the `recommendations` array. Pick the entries with the highest `confidence_score` values.

### Step 2 — Create the Split Test

Use the `element_selector` as the `selector` and `change_type` as the `op`:

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero CTA Optimization",
    "page": "/home",
    "type": "nocode",
    "goal": "click_through_rate",
    "auto_stop_days": 14,
    "variants": [
      {
        "label": "Variant B — new copy + color",
        "changes": [
          {
            "selector": "button.hero-cta",
            "op": "text",
            "value": "Start Free Trial"
          },
          {
            "selector": "button.hero-cta",
            "op": "css",
            "value": { "backgroundColor": "#ff6b35" }
          }
        ]
      }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/split-tests"
```

### Step 3 — Approve

Open the `approval_url` from the response and click **Activate test** (or approve in chat if your agent is connected over MCP).

### Step 4 — Monitor Results

Use the details endpoint, the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) and the Humblytics dashboard to track experiment performance over time.

***

## Using the Split Testing API with AI Agents

The simplest path is to connect your agent over MCP from the **Agents** page (`/agent`): it gets `get_split_test_recommendations`, `create_split_test`, `activate_split_test`, `list_split_tests`, `get_split_test`, `update_split_test` and `stop_split_test` as tools, with no endpoints to describe. See [MCP & API Access](https://docs.humblytics.com/api-access-and-agents.md).

If your agent cannot use MCP, the instructions below teach it the REST API. Replace `PROPERTY_ID` with your property ID and keep the key in the `HUMBLYTICS_API_KEY` environment variable.

### Instructions for your agent

Add this to your project's `CLAUDE.md`, `AGENTS.md`, `.cursor/rules` or your agent's system prompt:

```
## Humblytics API

Prefer the Humblytics MCP server if it is connected. Otherwise you have access to the Humblytics REST API for analytics and A/B testing. Call these endpoints with curl or fetch.

- Base URL: https://app.humblytics.com/api/external/v1
- Property ID: PROPERTY_ID
- API Key: stored in environment variable HUMBLYTICS_API_KEY
- Auth header: Authorization: Bearer $HUMBLYTICS_API_KEY

### Split Testing Endpoints

1. GET /properties/{propertyId}/split-test-recommendations?page={page}
   - Returns AI-powered A/B test recommendations for a page
   - Response includes: overall_analysis, key_insights, recommendations[] with element_selector, change_type (text|css), control_value, variant_value, confidence_score (0-100), expected_impact

2. POST /properties/{propertyId}/split-tests
   - Creates a split test with `status: "draft"`. It does not go live until a person activates it from the approval_url in the response. Two types supported:
   - type: "nocode" — Visual/DOM test. Body: { name, page, type: "nocode", goal?, auto_stop_days?, variants: [{ label?, changes: [{ selector, op, value }] }] }
     - op is one of: text | css | html | image | delete | duplicate
   - type: "redirect" — Redirect test. Body: { name, page, type: "redirect", goal?, auto_stop_days?, variants: [{ label?, url }] }
     - url is the path to redirect to (must differ from page and be unique across variants)
   - Goal options: click_through_rate, form_submissions, bounce_rate, session_time, page_funnel, external_page_funnel, revenue
   - auto_stop_days: 1–30 (default 30), 0 = no auto stop. 1–3 variants.
   - Map recommendation fields: element_selector → selector, change_type → op, variant_value → value

### Split Test Management Endpoints

3. GET /properties/{propertyId}/split-tests?status=draft|active|complete
   - List all experiments (key: experiments), optionally filtered by status

4. GET /properties/{propertyId}/split-tests/{experimentId}
   - Get full experiment details with per-variant metrics

5. PATCH /properties/{propertyId}/split-tests/{experimentId}
   - Update a draft or active experiment. Body: { name?, auto_stop_days? }

6. POST /properties/{propertyId}/split-tests/{experimentId}/stop
   - Stop a running experiment or discard a draft. Body: { reason? }

### Analytics Endpoints (for monitoring)

7. GET /properties/{propertyId}/traffic/trends?start={date}&end={date}&granularity=day
   - Time-series page views and unique visitors

8. GET /properties/{propertyId}/traffic/summary?start={date}&end={date}
   - Aggregate metrics: pageviews, sessions, bounce rate, avg session duration

9. GET /properties/{propertyId}/traffic/realtime
   - Live visitor count and feed (no date params needed)

10. GET /properties/{propertyId}/traffic/breakdown?start={date}&end={date}&limit=20
    - Top traffic segments: UTM, countries, devices, landing pages, referrers

11. GET /properties/{propertyId}/traffic/entry-exit-pages?start={date}&end={date}
    - Top entry and exit pages

12. GET /properties/{propertyId}/pages/breakdown?start={date}&end={date}
    - All page performance: views, visitors, scroll depth, bounce rate

13. GET /properties/{propertyId}/pages/details?page={path}&start={date}&end={date}
    - Single page deep dive with UTM, device, country breakdowns

14. GET /properties/{propertyId}/clicks/breakdown?start={date}&end={date}
    - Click events grouped by page and target

15. GET /properties/{propertyId}/clicks/details?page={path}&start={date}&end={date}
    - Clicks for a specific page

16. GET /properties/{propertyId}/forms/breakdown?start={date}&end={date}
    - Form submissions grouped by page and form target

17. GET /properties/{propertyId}/forms/details?page={path}&start={date}&end={date}
    - Form details for a specific page

18. GET /properties/{propertyId}/funnels?steps={json}&start={date}&end={date}&mode=sequential
    - Run a funnel query; steps is a JSON array of { name, conditions: [{ type: "page_view", path } | { type: "event", action }] }

19. GET /properties/{propertyId}/funnels/suggestions?search={text}
    - Pages, click targets, forms and conversion events available as funnel steps

All dated endpoints take start and end as ISO-8601 dates and an optional timezone; traffic/realtime and funnels/suggestions need no dates.

### Workflow

When asked to optimize a page or run an A/B test:
1. Fetch recommendations for the target page using the recommendations endpoint
2. Present the recommendations to the user with confidence scores and expected impact
3. Ask which recommendations to implement (or suggest high-confidence ones above 70)
4. Create the split test using the selectors and values from the chosen recommendations
5. Give the user the experiment ID and the approval_url; the test starts only after they activate it
6. Use the split test details endpoint to monitor per-variant metrics

When asked to check analytics or site performance:
1. Use traffic/summary for a quick overview, traffic/trends for time-series data
2. Use traffic/breakdown for segment analysis
3. Use pages/breakdown or pages/details for page-level analysis
4. Use clicks/breakdown or forms/breakdown for event-level data
5. Use funnels to analyze conversion paths
```

### Example Agent Conversation

Here is what a typical interaction looks like when an AI agent uses the Split Testing API:

**User**: "Optimize my homepage for more signups"

**Agent workflow**:

1. The agent calls `GET /properties/prop_abc123/split-test-recommendations?page=/home` and receives 3 recommendations.
2. The agent presents them:

   > I found 3 optimization recommendations for `/home`:
   >
   > 1. **Hero CTA Text** (confidence: 84) — Change "Learn More" → "Start Free Trial" — Expected impact: High (8%+)
   > 2. **Hero CTA Color** (confidence: 71) — Change gray background → orange — Expected impact: Medium (3-8%)
   > 3. **Subheading Copy** (confidence: 58) — Shorten subheading from 2 lines to 1 — Expected impact: Low (<3%)
   >
   > I'd recommend testing #1 and #2 together since they both target the hero CTA and have high confidence. Want me to create this experiment?
3. User confirms. The agent calls `POST /properties/prop_abc123/split-tests` with the selected recommendations mapped to a variant.
4. The agent confirms:

   > Experiment drafted (ID: `0c1f8f0e-…`). It is waiting for your approval — open <https://app.humblytics.com/p/prop\\_abc123/split-tests/0c1f8f0e-…> and click **Activate test**. It will auto-stop 14 days after it starts.

***

## Errors

The Split Testing API uses the same error format as the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md#errors), except where noted.

| Status | Code                                                                   | When it happens                                                                                     |
| ------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`                                                      | Missing required fields, name over 100 characters, bad `auto_stop_days`, or malformed variant data. |
| `401`  | `unauthorized`                                                         | Missing or invalid API key header.                                                                  |
| `402`  | `plan_limit_reached`                                                   | No active-test slot left on the plan. Flat body: `{ "error", "limit", "current" }`.                 |
| `403`  | `forbidden`                                                            | Property ID does not match the API key, or activation attempted without the approval header.        |
| `403`  | `launch_not_allowed`                                                   | **Launch tests** is off for this key (activation only).                                             |
| `404`  | `not_found`                                                            | The experiment (or `draft_id`) does not exist on this site.                                         |
| `409`  | `invalid_state`                                                        | The experiment is already complete (update, stop) or not a draft (activate).                        |
| `409`  | `too_many_drafts`                                                      | The site already has 10 tests waiting for approval.                                                 |
| `409`  | `draft_already_started`                                                | The `draft_id` is already running or starting.                                                      |
| `422`  | `copy_not_found_on_page`, `page_unreachable`, `audit_page_not_on_site` | A `draft_id` could not be placed on the page automatically.                                         |
| `429`  | `rate_limit_exceeded`                                                  | Recommendations only. Flat body: `{ "error", "reason", "usage", "limits" }`.                        |
| `500`  | `internal_error`                                                       | Unexpected server error. Retry later or contact support.                                            |
| `503`  | `service_unavailable`                                                  | The AI (recommendations) or screenshot (preview) service is not available.                          |
| `503`  | `subscription_status_unavailable`                                      | Subscription status could not be read. Retry shortly.                                               |

***

## Approval of agent-created tests

Split tests created through this API, or by an agent over MCP, are never served automatically. They arrive with `status: "draft"` and reach no visitor until a person approves them, in one of two ways:

* **In chat.** An agent connected over MCP can call `activate_split_test`. Your MCP client shows every change in a confirmation prompt; the test goes live only if you approve. If the client cannot show a prompt, the tool returns the `approval_url` instead.
* **From the link.** Open the test's `approval_url` (`https://app.humblytics.com/p/{propertyId}/split-tests/{experimentId}`) and click **Activate test**. If the reviewer is signed out, they are sent to sign in and then land on the test. Share the link with your team.

Per key, in-chat launching can be turned off with the **Launch tests** switch on the **Agents → API keys** tab. With it off, `activate_split_test` answers `launch_not_allowed` and the link is the only way to approve. Creating a draft never needs it.

* Activating takes an active-test slot, so it can be blocked by your plan's limit. See [Plan Limits & Upgrades](https://docs.humblytics.com/understanding-your-data/plan-limits-and-upgrades.md).
* To decline a proposed test, stop it through the API (a draft is discarded) or archive it from the **⋯** menu on its page.
* A stopped test cannot be restarted. Create a new test instead.

***

## Best Practices

* **Start with recommendations.** Always fetch recommendations before creating a test — they are based on your actual data and give you the highest-probability wins.
* **Test one hypothesis at a time.** While you can bundle multiple changes into a single variant, keep tests focused so you can attribute results clearly.
* **Set auto-stop durations.** Tests auto-stop after 30 days by default; set `auto_stop_days` lower for high-traffic pages. 14 days is a good default for most sites.
* **Use high-confidence recommendations first.** Prioritize recommendations with `confidence_score` above 70 for the best chance of statistically significant results.
* **Monitor with the analytics API.** Combine the Split Testing API with the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) to track experiment performance programmatically.
* **Review before launching.** When using AI agents, always review recommendations before creating tests — the agent should present options and ask for confirmation, and the person approves the draft before it runs.
