Surface docsObjects
The fields of the objects the tools return.
Dates are ISO 8601 strings. A tool's result wraps these objects as its reference shows, e.g.
surface_get returns { surface: Surface, dashboard_url }.
Surface
One page placement that serves variants.
| Field | Type | Description |
|---|---|---|
id | integer | The surface_id every tool takes. |
name | string | Unique within the organization. |
description | string | Free text. |
paradigm | RANKING | VARIANT_SELECTION | How variants are chosen. |
status | ACTIVE | ARCHIVED | Archived surfaces stop serving and don't count toward plan limits. |
live_state | LIVE | STALE | NOT_INSTALLED | NOT_INSTALLED until the snippet first reports in; LIVE if it reported in the last 7 days; otherwise STALE. |
page_url | string | The page the surface runs on. |
edge_route | string | The /api/<route> the surface serves on. |
edge_url | string | The URL the snippet fetches variants from. |
location | WORLDWIDE | UNITED_STATES | EUROPE | ASIA_PACIFIC | Serving region. |
segments_enabled | boolean | Whether segments give audiences their own variants. |
organization | { id, name } | The organization that owns the surface. |
first_integration_at | string | null | When the snippet first reported in. |
last_seen_at | string | null | When the snippet last reported in. |
created_at | string | Creation time. |
updated_at | string | Last change. |
Variant
One version of a surface's content.
| Field | Type | Description |
|---|---|---|
id | integer | The variant_id that variant tools take. |
raw_contents | string | JSON object of field key to value, e.g. {"headline": "…"}. |
status | DRAFT | ACTIVE | PAUSED | ARCHIVED | Only ACTIVE variants are served; only DRAFT variants can be edited. |
is_control | boolean | The page's current copy, which the others are measured against. One per segment. |
segment | Segment | null | The audience this variant serves; null for everyone. |
created_at | string | Creation time. |
Segment
An audience with its own variants, matched by a query parameter or a path pattern.
| Field | Type | Description |
|---|---|---|
id | integer | The segment_id a variant takes in variant_create. |
name | string | Unique within the surface. |
match_type | QUERY_PARAM | PATH_VARIABLE | How visitors are matched. |
param_key | string | QUERY_PARAM: the query parameter, e.g. utm_source. |
param_value | string | The value that matches. |
path_pattern | string | PATH_VARIABLE: the path pattern with one capture. |
surface_id | integer | The surface it belongs to. |
created_at | string | Creation time. |
Test
The bandit test a surface runs; surface_results reports the most recently started.
| Field | Type | Description |
|---|---|---|
id | integer | The test id. |
name | string | e.g. "Pricing hero — Book Demo Click". |
event_type | string | The goal event it optimizes. |
target_metric | RATE_PER_SESSION | TOTAL_EVENTS | What counts as better. |
target_policy | MAXIMIZE | MINIMIZE | Which direction is better. |
start | string | When the test started. |
VariantResult
One variant's results in the latest test.
| Field | Type | Description |
|---|---|---|
variant_id | integer | Matches Variant.id. |
is_control | boolean | Whether it is the control. |
contents | object | The variant's field values, parsed. |
sessions | integer | Sessions that were served this variant. |
sessions_w_event | integer | Of those, sessions that reached the goal. |
rate_per_session | number | sessions_w_event / sessions. |
win_probability | number | The bandit's estimated chance this variant is best, 0–1. |
Termination
The bandit's own judgement on whether the test is done.
| Field | Type | Description |
|---|---|---|
should_terminate | boolean | True when one variant is clearly best. |
estimated_winner_ctr | number | The leading variant's estimated goal rate. |
value_remaining_pctile | number | The potential value remaining from running the test longer. |
Traffic
All-time events for a surface, as the Analytics page shows them.
| Field | Type | Description |
|---|---|---|
alltime_session_count | integer | Sessions that rendered the surface. |
event_stats | { [event_type]: { count, avg_count_per_session, rate_per_session } } | Per event: total count, average per session, and the share of sessions with at least one. |