> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Measurement & Incrementality

> Configure event sources, ingest measurement data, and run incrementality tests with the v2 measurement engine

## Overview

Apostra Measurement Engine turns raw advertising signals into causal evidence about what is working. Instead of treating every conversion as proof, it asks the harder question — *would that conversion have happened anyway?* — and updates a running set of beliefs about each campaign's incremental impact as new data arrives.

The pipeline has four layers:

1. **Event sources** — buyer-registered pixels, SDKs, MMPs, CRMs, or measurement partners that send conversions, impressions, or outcome data.
2. **Measurement data** — privacy-safe outcome records (revenue, conversions, LTV) attached to a campaign, media buy, package, or creative.
3. **Belief state** — a Bayesian summary of what the engine currently believes about each hypothesis (e.g. "audience segment A drives more incremental revenue than segment B"), expressed as posterior distributions with confidence intervals.
4. **Incrementality tests** — explicit treatment / control / observation cohorts and test plans that produce stronger causal estimates than passive observation.

> [!NOTE]
>
> **How belief updating works (high level)**
> The engine starts each hypothesis with a prior — your initial guess about
> size and confidence. As measurement records arrive, the learning cycle
> updates that prior into a posterior using Bayesian inference: high-quality,
> fresh data shifts beliefs faster; sparse or noisy data shifts them less.
> Running an A/B test with proper test and control cohorts produces the
> strongest evidence and tightens the posterior fastest.

> [!WARNING]
>
> **Privacy-first**: the measurement engine never accepts raw PII (plain emails,
> phone numbers, addresses). Send pre-hashed identifiers (SHA-256) or
> pre-resolved identity tokens (RampID, UID2, ID5, etc.) — see the
> [Conversion API guide](https://docs.apostra.com/v2/integrations/conversion-api.md) for hashing rules.

## How evidence stays with the advertiser

Measurement sources, records, hypotheses, test plans, learning records, and
belief state are stored under the advertiser scope. They are not separate
seller-owned histories. When a measured campaign uses more than one seller,
authorized users and agents can read its submitted outcomes from the same
advertiser-scoped endpoints and use that evidence when planning later work
across sellers.

This evidence exists only when measurement is configured and data is submitted.
A seller relationship or campaign by itself does not create outcome evidence,
and seller delivery data is available only when the seller returns it.

> [!NOTE]
>
> Advertiser-scoped evidence is durable product state, not private model memory
> carried by an individual agent. Access follows the customer and advertiser
> permissions on every request. Changing sellers does not move the records into
> a seller account or grant that seller access. Belief state remains read-only:
> new data, a new test, human feedback, or a new hypothesis is required before a
> later learning cycle can change it.

## Prerequisites

**1. Apostra API key**

Generate a key at [app.apostra.com/user-api-keys](https://app.apostra.com/user-api-keys).
See [Authentication](https://docs.apostra.com/v2/authentication.md) for setup.

**2. Advertiser ID**

All measurement endpoints are scoped to an advertiser. You'll use this in
every URL: `/api/v2/buyer/advertisers/:advertiserId/...`.

**3. A campaign or media buy (recommended)**

Measurement data is most useful when attached to in-flight campaigns.
See [Campaigns](https://docs.apostra.com/v2/object-guides/campaign.md) for setup.

All examples below use:

```
BASE = https://api.apostra.com/api/v2/buyer
AUTH = Authorization: Bearer scope3_<your_api_key>
```

## Step 1: Register Event Sources

An **event source** is a logical channel through which measurement events flow — a website pixel, a mobile SDK, a CRM export, or an MMP feed. Every event you send must reference a registered `event_source_id`.

Use the ADCP-spec sync endpoint to upsert event sources for an advertiser:

```bash cURL theme={null}
curl -X POST "$BASE/advertisers/12345/event-sources/sync" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": { "account_id": "12345" },
    "event_sources": [
      {
        "event_source_id": "website_pixel",
        "name": "Website Pixel",
        "event_types": ["purchase", "add_to_cart", "lead"],
        "allowed_domains": ["shop.example.com", "checkout.example.com"],
        "example_event": {
          "event_type": "purchase",
          "hashed_email": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
          "value": 89.99,
          "currency": "USD"
        }
      },
      {
        "event_source_id": "crm_import",
        "name": "Salesforce CRM Export",
        "event_types": ["purchase", "qualify_lead"],
        "allowed_domains": []
      }
    ],
    "delete_missing": false
  }'
```

> [!WARNING]
>
> Identifiers like `hashed_email` and `hashed_phone` MUST be SHA-256 hex
> (lowercase, 64 chars). Normalize email to lowercase / trimmed and phone to
> E.164 *before* hashing — see the
> [Conversion API guide](https://docs.apostra.com/v2/integrations/conversion-api.md) for full hashing
> rules. The engine silently drops malformed hashes.

> [!WARNING]
>
> Leaving `allowed_domains` empty (or omitting it) means events from **any
> origin** will be accepted for that source. Always restrict `allowed_domains`
> to the hosts that legitimately fire your pixel; an empty list is appropriate
> only for server-to-server feeds (CRM, MMP) where there is no browser origin.

```json Response theme={null}
{
  "event_sources": [
    {
      "event_source_id": "website_pixel",
      "action": "created",
      "setup": {
        "snippet_type": "server_only",
        "instructions": "Events are ingested server-to-server. Send accepted events to POST /api/v2/advertisers/12345/log-event using your API credentials. Setup guide: https://docs.apostra.com/v2/guides/log-events"
      }
    },
    { "event_source_id": "crm_import", "action": "created" }
  ]
}
```

> [!NOTE]
>
> Live results (`created`, `updated`, `unchanged`) carry a `setup` object so
> install guidance travels with the response, not only inside the widget.
> Apostra ingests every source server-to-server via `log_event`, so
> `snippet_type` is always `server_only` and no client-side `snippet` is
> returned; `instructions` names the ingestion endpoint and links the setup
> guide. `failed` and `deleted` results omit `setup`.

### Request fields

| Field | Type | Required | Description |
| - | - | - | - |
| `account.account_id` | string | yes | Must match the `:advertiserId` in the URL |
| `event_sources[].event_source_id` | string | yes | Buyer-assigned ID, max 255 chars |
| `event_sources[].name` | string | no | Human-readable label |
| `event_sources[].event_types` | string\[] | no | Restricts which event types this source may send. Omit to accept all. |
| `event_sources[].allowed_domains` | string\[] | no | Origin domains authorized for this source |
| `delete_missing` | boolean | no | Archive any buyer-managed sources not in this payload (default `false`) |

Each result's `action` is one of `created`, `updated`, `unchanged`, `failed`, or `deleted`.

### List configured sources

```bash theme={null}
curl "$BASE/advertisers/12345/event-sources?take=50&skip=0" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

> [!TIP]
>
> Events sent to an unregistered `event_source_id` are rejected. Always sync
> sources before turning on a pixel or CRM job.

### How a source reaches each seller account

You define an event source once, for the advertiser. On a platform where you
own the ad account, such as Meta or Snap, the seller optimizes against a pixel
that already exists on that account: a Meta dataset or a Snap Pixel. Apostra
binds your event source to that pixel separately on each seller account. It
never creates a pixel on the account and never sends your events while binding.

For the step-by-step version, see
[Use your event sources and audiences on each seller
account](https://docs.apostra.com/v2/guides/map-event-sources-and-audiences.md).

Binding starts when you save the pixel for a seller account with
`sellerAccounts`, and again when you create a media buy whose optimization goal names the event
source. For each seller account, Apostra lists the pixels on that account and
checks the one you named. It never picks a pixel for you:

1. If you named a pixel for that account and it is on the account, Apostra
   binds it, as long as the pixel accepts every event type the source is used
   for (below). If it is not on the account, the account reports
   `SELLER_EVENT_SOURCE_DESTINATION_MISSING`; Apostra never binds a different
   one instead.
2. If you named none and a pixel on the account has exactly your source's
   own `eventSourceId` as its id, Apostra binds that pixel, as when you
   registered a Meta pixel's id as the event source. If you named none and no
   pixel has that id, the account reports
   `SELLER_EVENT_SOURCE_DESTINATION_AMBIGUOUS` when it has pixels, even just
   one. Name the pixel to use.
3. If you named none and the account has no pixel, the account reports
   `SELLER_EVENT_SOURCE_DESTINATION_MISSING`.

A pixel that lists the event types it accepts can only be bound to a source
whose `eventTypes` are all on that list. A source without `eventTypes` is used
for every type, so it binds only to a pixel that lists none. Otherwise the
account reports `SELLER_EVENT_SOURCE_DESTINATION_MISSING`: name a pixel that
accepts those types, or narrow the source's `eventTypes`. Either blocker
leaves the account `pending` until you fix it. When the account's inventory
already lists the pixel and its event types do not fit, `save_event_source`
refuses the pixel when you save it, with `VALIDATION_ERROR` on that entry's
`platformId`, instead of waiting for the account to report a blocker.

To name the pixel, save the source with `sellerAccounts` through
[`save_event_source`](https://docs.apostra.com/v3/tool-reference). Binding sends none of
your conversion data, so it does not depend on the **Conversion events**
switch in Connections. Read `sellerAccounts` on the event source to see the
pixel named for each account (`platformId`), its `status`, which says whether
the pixel is bound yet, and any blocker. A seller whose
platform cannot bind event sources reports `SELLER_OBJECT_TYPE_UNSUPPORTED`.

Once an account is bound, later media buys on that account use the same
pixel without binding again.

#### What the media buy sends

The platforms accept only their own pixel ID in a conversion goal. So when a
media buy's optimization goal names one of your event sources, the media buy
Apostra creates on Snap, Meta or TikTok carries the pixel bound on that
seller account instead of your `event_source_id`. Your media buy keeps
showing your own `event_source_id`; only the request sent to the seller
changes. Event sources the seller manages, and the platform's own built-in
events, are sent unchanged.

Where the binding stands on the seller account decides what happens to a new
media buy:

| Binding on the seller account | What happens to the media buy | What to do |
| - | - | - |
| Bound | Sent with the bound pixel. | Nothing. |
| Still being bound | Not sent yet. Launching reports `SELLER_OBJECT_SYNC_PENDING` for the buy, which stays a draft. On the launch tick, Apostra checks again about every 30 seconds and sends the buy once the pixel is bound. For an approved buy, Apostra checks again about every 2 minutes before forwarding it. Waiting does not use up the retries used to send the buy or keep its campaign launch moving. | Nothing. |
| `SELLER_EVENT_SOURCE_DESTINATION_MISSING` | Fails with that code. | Create the pixel in the platform's own console, or name a pixel that is on the account with `sellerAccounts`. Then create a new media buy. |
| `SELLER_EVENT_SOURCE_DESTINATION_AMBIGUOUS` | Fails with that code. This also happens when two of your connected seller accounts for the same ad account have different pixels bound. | Name the pixel to use with `sellerAccounts`. Then create a new media buy. |
| `SELLER_DATA_SHARING_NOT_PERMITTED` | Fails with that code. | Turn on **Conversion events** for that seller in Connections. Then create a new media buy. |
| `SELLER_OBJECT_TYPE_UNSUPPORTED` | Fails with that code. The seller cannot use your event sources: a managed seller agent, an AdCP agent outside Apostra, a platform that cannot bind them, or an ad account that is not one of your connected seller accounts. | Optimize the buy toward a metric instead, or buy from a seller account that can bind your event sources. |
| `SELLER_OBJECT_SYNC_FAILED`, `SELLER_OBJECT_SYNC_EXPIRED` or `SELLER_OBJECT_SYNC_RECONCILIATION_REQUIRED` | Fails with that code: Apostra could not confirm a pixel on the account. | Submit a new media buy or contact support. |

A failed media buy shows the code at the start of its failure reason. On a
seller that approves media buys by hand, the buy waits or fails before it
reaches the seller's approval queue, and the approved buy is sent with the
bound pixel.

#### Updating a media buy

An update to a media buy the seller already holds is checked the same way.
When the update's optimization goals name one of your event sources, Apostra
checks the binding on the seller account before saving anything. If the
binding reports one of the codes in the table above, the update fails with
that code and your media buy stays as it was: fix what the table says, then
send the update again. An update cannot wait for a binding that is not
finished, so it fails with `SELLER_OBJECT_SYNC_PENDING` instead and changes
nothing; send it again once `sellerAccounts` on the event source shows the
account bound. An update does not start binding: binding starts when you
create a media buy that names the event source on that account. An update,
like a new media buy, never binds a pixel you have not named for the account.

When the update is sent to the seller, it carries the bound pixel instead of
your `event_source_id`, and your media buy keeps showing your own id. An
update that changes only optimization goals is saved on your media buy but is
not sent to the seller.

What you still need to do yourself:

* Create the pixel or dataset in the platform's own console if the account has
  none, and install it on your site or app so it receives events. Binding
  connects to an existing pixel; it does not install one.
* Grant Apostra access to the pixel or dataset when you connect the account
  (see [Connecting ad platforms](https://docs.apostra.com/v2/guides/connecting-ad-platforms.md)).
* Keep sending your conversion events to Apostra through
  [`log_event`](https://docs.apostra.com/v2/guides/log-events). Binding records which pixel your goal
  uses on each account; it does not forward events to the seller.

## Step 2: Configure Measurement

Measurement configuration controls which measurement features are active for an advertiser — Marketing Mix Modeling (MMM), incrementality testing, and brand lift — plus any provider-specific MMM settings.

```bash theme={null}
curl -X PUT "$BASE/advertisers/12345/measurement-config" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mmmEnabled": true,
    "mmmConfig": {
      "provider": "measured",
      "dataSourceIds": ["ds_revenue", "ds_orders"],
      "reportingFrequency": "weekly"
    },
    "brandLiftEnabled": false,
    "settings": {
      "defaultLookbackDays": 28
    }
  }'
```

### Fields

| Field | Type | Description |
| - | - | - |
| `mmmEnabled` | boolean | Enable Marketing Mix Modeling |
| `mmmConfig.provider` | string | MMM partner name (e.g. `measured`) |
| `mmmConfig.dataSourceIds` | string\[] | IDs of upstream data feeds powering MMM |
| `mmmConfig.reportingFrequency` | enum | `weekly`, `monthly`, or `quarterly` |
| `brandLiftEnabled` | boolean | Enable brand-lift study integration |
| `settings` | object | Free-form key/value advertiser-level overrides |

`PUT` is upsert — pass only the fields you want to set; missing fields fall back to defaults / prior values. Read the current config with `GET /advertisers/:advertiserId/measurement-config`.

## Step 3: Validate Configuration

Before relying on incrementality estimates, assess whether your planned spend, geos, and flight length can actually move the needle on a hypothesis. The testability assessment returns power-analysis-style guidance.

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/testability" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "hypothesisIds": ["1f5c0c4e-2c9f-4f0a-9e31-2d4f3c7b1a01"],
    "budget": 250000,
    "weeklyBudget": 25000,
    "flightWeeks": 10,
    "testGeos": ["US-CA", "US-OR", "US-WA"],
    "controlGeos": ["US-AZ", "US-NV", "US-NM"]
  }'
```

The response surfaces, per hypothesis, whether the design has enough cells, whether geos are well-matched, and which gaps would weaken inference.

> [!TIP]
>
> Run testability *before* launching media. It's far cheaper to widen your geo
> list or extend the flight than to discover post-flight that the test was
> underpowered.

## Step 4: Send Measurement Data

There are two complementary ways to feed the engine:

* **Conversion events** — fine-grained, per-user actions (purchases, leads, sign-ups). Use the [Conversion API](https://docs.apostra.com/v2/integrations/conversion-api.md) — same identity rules apply.
* **Measurement records** — pre-aggregated outcomes for a time window and geo (e.g. "incremental revenue, US-CA, week of 2026-03-01 = \$8,450"). Use the sync endpoint below.

### Sync aggregated measurement data

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/measurement-data/sync" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [
      {
        "start_time": "2026-03-01T00:00:00-05:00",
        "end_time":   "2026-03-07T23:59:59-05:00",
        "metric_id":  "incremental_revenue",
        "metric_value": 8450.75,
        "unit": "currency",
        "currency": "USD",
        "campaign_id": "camp_456",
        "media_buy_id": "mb_789",
        "source": "advertiser",
        "source_platform": "billy_grace",
        "source_metric_name": "Incremental Revenue",
        "external_row_id": "bg_row_001"
      },
      {
        "start_time": "2026-03-01T00:00:00-05:00",
        "end_time":   "2026-03-07T23:59:59-05:00",
        "metric_id":  "purchase_count",
        "metric_value": 142,
        "unit": "count",
        "campaign_id": "camp_456",
        "external_row_id": "bg_row_002"
      }
    ]
  }'
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `start_time` / `end_time` | ISO 8601 | yes | Must include offset; `start_time < end_time` |
| `metric_id` | enum | yes | `revenue`, `incremental_revenue`, `conversions`, `incremental_conversions`, `page_view_count`, `add_to_cart_count`, `purchase_count`, `ltv_1d`, `ltv_7d`, `ltv_30d` |
| `metric_value` | number | yes | The measured value |
| `unit` | enum | yes | `currency`, `count`, `ratio`, `percentage` |
| `currency` | string | conditional | ISO 4217 — required when `unit` is `currency` |
| `campaign_id` / `media_buy_id` / `package_id` / `creative_id` | string | one required | Attaches the measurement to an entity |
| `source` | enum | no | `advertiser`, `mmp`, or `measurement_partner` |
| `external_row_id` | string | no | Idempotency key for re-syncs |

Up to **1,000 measurements per call**. Each result reports `action: created | updated | unchanged | failed`.

### Upload raw measurement records (advanced)

For research-style flows that already produce per-geo outcomes, the learning engine accepts batched records directly:

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/measurement-records" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "outcomeType": "incremental_revenue",
        "geo": "US-CA",
        "timeWindowStart": "2026-03-01",
        "timeWindowEnd":   "2026-03-07",
        "value": 8450.75,
        "baselineValue": 7100.00,
        "confidenceInterval": 0.92,
        "source": "measured",
        "lagDays": 7
      }
    ]
  }'
```

Up to **5,000 records per call**.

### Upload context records

Context records describe market conditions that the learning engine should partial out — promos, weather, competitor activity, seasonality:

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/context-records" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "geo": "US-CA",
        "timeWindowStart": "2026-03-01",
        "timeWindowEnd":   "2026-03-07",
        "promoActive": true,
        "promoType": "site_wide_15_off",
        "seasonalityIndex": 1.12,
        "flightStatus": "active"
      }
    ]
  }'
```

> [!WARNING]
>
> Never include raw user identifiers (emails, phone numbers, names) in
> measurement or context records. These endpoints accept aggregated outcomes
> only — per-user events go through the [Conversion API](https://docs.apostra.com/v2/integrations/conversion-api.md).

## Step 5: Inspect the Event Summary

Once events are flowing, the event-summary endpoint returns hourly counts per event type so you can confirm ingestion before depending on downstream attribution:

```bash theme={null}
curl "$BASE/advertisers/12345/events/summary?\
eventType=conversion&\
startHour=2026-03-27T14:00:00Z&\
endHour=2026-03-27T20:00:00Z" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

```json Response theme={null}
{
  "periodStart": "2026-03-27T14:00:00.000Z",
  "periodEnd":   "2026-03-27T20:00:00.000Z",
  "entries": [
    { "eventHour": "2026-03-27T14:00:00.000Z", "eventType": "conversion", "eventCount": 1500 },
    { "eventHour": "2026-03-27T15:00:00.000Z", "eventType": "conversion", "eventCount": 1612 },
    { "eventHour": "2026-03-27T16:00:00.000Z", "eventType": "conversion", "eventCount": 1483 }
  ],
  "totalEventCount": 4595
}
```

| Query param | Notes |
| - | - |
| `eventType` | One of `conversion`, `click`, `impression`, `measurement`, `mmp`. Omit for all types. |
| `startHour` / `endHour` | Hour-aligned ISO 8601 timestamps. Defaults to the last completed UTC hour. |

You can also check measurement freshness — gaps in expected geo/time coverage:

```bash theme={null}
curl "$BASE/advertisers/12345/measurement-freshness?\
flightStart=2026-03-01&\
flightEnd=2026-04-30&\
geos=US-CA,US-OR,US-WA" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

## Step 6: Set Up Test Cohorts and Test Plans

Incrementality tests work by comparing well-defined groups. The v2 model has three layers:

* **Hypotheses** — *what* you're testing: a falsifiable claim about a treatment vs. a comparison ("premium CTV drives more incremental revenue per impression than general CTV"). Hypotheses are persistent — each test plan accumulates evidence against the same hypothesis over time.
* **Test cohorts** — *who* is in each arm (treatment, control, observation). A cohort is a flexible audience definition (geo, segment, zip code, custom).
* **Test plans** — *how* the comparison runs against a hypothesis: which conditions, which dimensions to match on, how cells are sized.

### Create a hypothesis

Every test plan is anchored to a hypothesis. Create one before linking test plans, cohorts, or allocation entries to it.

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/hypotheses" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "channel",
    "statement": "Premium CTV inventory drives more incremental purchases than general CTV at the same CPM.",
    "treatment": "Premium CTV (top-tier publisher list)",
    "comparison": "General CTV (open marketplace)",
    "outcomeMetric": "incremental_revenue",
    "icon": "📺",
    "priorConfidence": 0.4,
    "priorMagnitude": 0.15,
    "incrementalCostCpm": 8.0,
    "measurementSource": "billy_grace",
    "measurementLagWeeks": 1,
    "minimumTestCells": 6,
    "proxyMetrics": [
      { "outcomeType": "add_to_cart_count", "weight": 0.3 },
      { "outcomeType": "purchase_count", "weight": 0.7 }
    ]
  }'
```

```json Response theme={null}
{
  "id": "1f5c0c4e-2c9f-4f0a-9e31-2d4f3c7b1a01",
  "advertiserId": "12345",
  "category": "channel",
  "statement": "Premium CTV inventory drives more incremental purchases than general CTV at the same CPM.",
  "treatment": "Premium CTV (top-tier publisher list)",
  "comparison": "General CTV (open marketplace)",
  "outcomeMetric": "incremental_revenue",
  "icon": "📺",
  "priorConfidence": 0.4,
  "currentConfidence": 0.4,
  "priorMagnitude": 0.15,
  "currentMagnitude": 0.15,
  "incrementalCostCpm": 8.0,
  "measurementSource": "billy_grace",
  "measurementLagWeeks": 1,
  "minimumTestCells": 6,
  "proxyMetrics": [
    { "outcomeType": "add_to_cart_count", "weight": 0.3 },
    { "outcomeType": "purchase_count", "weight": 0.7 }
  ],
  "groundTruth": null,
  "status": "no_buys",
  "confidenceHistory": [],
  "createdBy": "user_98765",
  "sourceName": null,
  "createdAt": "2026-04-26T16:00:00.000Z",
  "updatedAt": "2026-04-26T16:00:00.000Z"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `category` | enum | yes | `audience`, `creative`, `channel`, `context`, `timing`, `tactic` |
| `statement` | string | yes | The falsifiable claim being tested |
| `treatment` | string | yes | Description of the treatment arm |
| `comparison` | string | yes | Description of the comparison / control arm |
| `outcomeMetric` | string | yes | Primary metric (e.g. `incremental_revenue`, `purchase_count`) |
| `priorConfidence` | number (0–1) | yes | Initial confidence before any data |
| `priorMagnitude` | number | yes | Expected effect size before any data |
| `icon` | string | no | Emoji for UI display, defaults to `💡` |
| `incrementalCostCpm` | number | no | Cost premium of treatment vs. comparison |
| `measurementSource` | string | no | Source key tying ground-truth records to this hypothesis |
| `measurementLagWeeks` | integer | no | Expected reporting lag, defaults to `1` |
| `minimumTestCells` | integer | no | Minimum cells required for a meaningful test, defaults to `6` |
| `proxyMetrics` | array | no | `{ outcomeType, weight }` proxies that update beliefs alongside the primary metric |
| `groundTruth` | object | no | Free-form expected outcome for sanity checks |

The returned `id` is the `hypothesisId` you'll plug into the test-plan creation step below — and into testability, learning-records, and belief-state queries.

#### Hypothesis status lifecycle

Every hypothesis carries a `status` that the engine advances as evidence accrues. New hypotheses always start at `no_buys`; the rest are reached automatically as media buys link, fire, and produce measurable outcomes.

| Status | Meaning | Triggered when |
| - | - | - |
| `no_buys` | Hypothesis exists but no media is running against it | Hypothesis is created and no allocation entries are linked yet |
| `in_market` | At least one linked buy is delivering | A linked allocation entry / media buy goes active |
| `partially_measured` | Some data has arrived, but coverage is thin | Measurement records start landing but cells / geos are below `minimumTestCells` or coverage gaps remain |
| `well_measured` | Enough data to update beliefs with confidence | Coverage hits `minimumTestCells` across the matched dimensions and the posterior tightens |
| `proven` | Posterior supports the treatment hypothesis | Belief converges with sufficient confidence in the hypothesized direction |
| `disproven` | Posterior rejects the treatment hypothesis | Belief converges with sufficient confidence against the hypothesized direction |

> [!TIP]
>
> You can filter hypotheses by status when listing —
> `GET /advertisers/:advertiserId/hypotheses?status=well_measured` is a useful
> default for "what's worth a stakeholder review this week."

### List hypotheses

```bash theme={null}
curl "$BASE/advertisers/12345/hypotheses?take=50&skip=0" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

Optional filters: `category`, `status`, `flightId`. Pagination via `take` (max 100) and `skip`.

### Create test cohorts

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/test-cohorts" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Treatment",
    "description": "Users in CA, OR, WA receiving full ad exposure",
    "cohortType": "geographic",
    "role": "TREATMENT",
    "definition": {
      "type": "geo_region",
      "regions": ["US-CA", "US-OR", "US-WA"]
    },
    "estimatedSize": 50000
  }'
```

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/test-cohorts" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mountain West Control",
    "cohortType": "geographic",
    "role": "CONTROL",
    "definition": {
      "type": "geo_region",
      "regions": ["US-AZ", "US-NV", "US-NM"]
    },
    "estimatedSize": 48000
  }'
```

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Cohort label, max 255 chars |
| `cohortType` | string | yes | Free-form classification (e.g. `geographic`, `demographic`, `behavioral`) |
| `role` | enum | no | `TREATMENT`, `CONTROL`, or `OBSERVATION` (default `TREATMENT`) |
| `definition.type` | string | yes | Discriminator — `zip_code`, `user_segment`, `geo_region`, `custom` |
| `definition.*` | any | — | Additional fields per type |
| `estimatedSize` | integer | no | Size estimate for power analysis |

Available cohort operations:

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/advertisers/:advertiserId/test-cohorts` | List (filter by `role`, `isActive`) |
| `POST` | `/advertisers/:advertiserId/test-cohorts` | Create |
| `GET` | `/advertisers/:advertiserId/test-cohorts/:id` | Get one |
| `PUT` | `/advertisers/:advertiserId/test-cohorts/:id` | Update |
| `DELETE` | `/advertisers/:advertiserId/test-cohorts/:id` | Archive |

### Create a test plan against a hypothesis

A hypothesis is the question being tested (e.g. "Does running on premium CTV inventory drive incremental purchases versus general CTV?"). Test plans are nested under the hypothesis they test:

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/hypotheses/1f5c0c4e-2c9f-4f0a-9e31-2d4f3c7b1a01/test-plans" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "testCondition":    { "inventoryTier": "premium_ctv" },
    "controlCondition": { "inventoryTier": "general_ctv" },
    "matchDimensions":  ["geo", "daypart", "audienceSegment"]
  }'
```

| Field | Type | Description |
| - | - | - |
| `testCondition` | object | What defines the treatment arm |
| `controlCondition` | object | What defines the control arm |
| `matchDimensions` | string\[] | Dimensions to balance across cells (at least one) |

### Activate a test plan and link media buys

Once a plan is created (status `designed`), patch it to `active` and link the allocation entries (media buys) that fall under each role:

```bash theme={null}
# Link allocations
curl -X POST "$BASE/advertisers/12345/test-plans/<test_plan_id>/link-buys" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "allocationEntryIds": [
      "a1111111-1111-1111-1111-111111111111",
      "a2222222-2222-2222-2222-222222222222"
    ],
    "role": "test"
  }'

# Activate
curl -X PATCH "$BASE/advertisers/12345/test-plans/<test_plan_id>" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'
```

`status` transitions: `designed` → `active` → `complete`. Updating to `complete` (or letting the engine auto-complete on flight end) closes the test for inference.

## Step 7: Trigger Learning and Read Belief State

The learning cycle ingests new measurement records, fits the Bayesian update, and refreshes the belief state. It typically runs on a schedule, but you can trigger it on demand after a large data load:

```bash theme={null}
curl -X POST "$BASE/advertisers/12345/learning-cycle/run" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

Read the current belief state for an advertiser:

```bash theme={null}
curl "$BASE/advertisers/12345/belief-state" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

The response summarizes each tracked hypothesis: posterior magnitude, confidence interval, status (`no_buys`, `in_market`, `partially_measured`, `well_measured`, `proven`, `disproven`), and which sources contributed evidence.

To inspect the records that fed the most recent updates:

```bash theme={null}
curl "$BASE/advertisers/12345/learning-records?\
hypothesisId=1f5c0c4e-2c9f-4f0a-9e31-2d4f3c7b1a01&\
take=50&skip=0" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

You can also query raw measurement records by outcome / geo / date range:

```bash theme={null}
curl "$BASE/advertisers/12345/measurement-records?\
outcomeType=incremental_revenue&\
geos=US-CA,US-OR&\
startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

> [!NOTE]
>
> Belief state is read-only. To change beliefs, send better data — more
> records, fewer gaps, properly designed test plans — and let the next
> learning cycle re-fit.

## Step 8: Review and Acknowledge Test Results

When a test plan reaches `complete`, the engine produces an incrementality result attached to the test plan and hypothesis. Read it via the test plan endpoint:

```bash theme={null}
curl "$BASE/advertisers/12345/test-plans/<test_plan_id>" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

The response includes the resolved test cell counts, control cell counts, coverage gaps (geos / dimensions where matching was weak), and the posterior delta on the hypothesis. List all plans for a hypothesis with:

```bash theme={null}
curl "$BASE/advertisers/12345/hypotheses/<hypothesis_id>/test-plans?take=50" \
  -H "Authorization: Bearer scope3_<your_api_key>"
```

### Mark results as reviewed

Acknowledge a result so it stops surfacing in unread-results queues and so the audit trail records who signed off. Use the test plan update endpoint to transition status (e.g. recording observed test/control cell counts and final coverage gaps):

```bash theme={null}
curl -X PATCH "$BASE/advertisers/12345/test-plans/<test_plan_id>" \
  -H "Authorization: Bearer scope3_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "complete",
    "testCellsCount": 12,
    "controlCellsCount": 11,
    "coverageGaps": []
  }'
```

If the result motivates a new line of inquiry, capture it as human feedback or as a new hypothesis on the advertiser — that becomes the prior for the next round of testing.

## Best Practices

> [accordion] Register event sources before turning on a pixel
>
> Events sent to an unknown `event_source_id` are rejected. Always run
> `sync_event_sources` first; for new advertisers, do this in your onboarding
> automation.

> [accordion] Send aggregated measurement records when you have them
>
> If your MMP / CRM / data warehouse can produce weekly per-geo outcomes,
> use `POST /measurement-data/sync` (or `/measurement-records`). Aggregated
> records arrive faster, are cheaper to ingest, and are immune to user-level
> identity-resolution drift.

> [accordion] Send raw events when you need fine-grained attribution
>
> For per-user attribution and click-id matching, use the
> [Conversion API](https://docs.apostra.com/v2/integrations/conversion-api.md). It's the only path that
> can attribute back to a specific impression or click.

> [accordion] Set good priors
>
> Hypothesis `priorConfidence` and `priorMagnitude` are not "the answer" —
> they reflect *what you'd believe before the test*. Calibrated priors make
> early-flight estimates much more useful than uncalibrated ones.

> [accordion] Match cohorts on the dimensions that move the metric
>
> `matchDimensions` should include any factor that meaningfully drives the
> outcome (geo, daypart, segment). Forgetting a strong driver introduces
> confounding even with a clean A/B split.

> [accordion] Use external\_row\_id for idempotency
>
> `measurement-data/sync` deduplicates on `external_row_id`. Re-running a
> daily export is safe — only changed rows update.

> [accordion] Hash before sending
>
> `hashed_email` and `hashed_phone` must be SHA-256 hex (lowercase, 64
> chars). Normalize email to lowercase / trimmed and phone to E.164 *before*
> hashing. The engine will not match malformed hashes.

> [accordion] Run testability before launch, freshness during flight
>
> `POST /testability` answers "is this design likely to learn anything?"
> before media starts. `GET /measurement-freshness` answers "is data
> actually arriving?" once it has.

> [accordion] Keep human feedback in the loop
>
> Posterior deltas are a guide, not a verdict. When stakeholders disagree
> with a result, capture the disagreement as feedback so the next cycle can
> spawn refined hypotheses rather than re-litigating the old one.

## Endpoint Reference

All paths are relative to `https://api.apostra.com/api/v2/buyer`.

### Event sources

| Method | Path |
| - | - |
| `POST` | `/advertisers/:advertiserId/event-sources/sync` |
| `GET` | `/advertisers/:advertiserId/event-sources` |

### Measurement config

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/measurement-config` |
| `PUT` | `/advertisers/:advertiserId/measurement-config` |

### Measurement data

| Method | Path |
| - | - |
| `POST` | `/advertisers/:advertiserId/measurement-data/sync` |
| `POST` | `/advertisers/:advertiserId/measurement-records` |
| `GET` | `/advertisers/:advertiserId/measurement-records` |
| `POST` | `/advertisers/:advertiserId/context-records` |

### Events and freshness

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/events/summary` |
| `GET` | `/advertisers/:advertiserId/measurement-freshness` |

### Learning engine

| Method | Path |
| - | - |
| `POST` | `/advertisers/:advertiserId/learning-cycle/run` |
| `GET` | `/advertisers/:advertiserId/belief-state` |
| `GET` | `/advertisers/:advertiserId/learning-records` |
| `POST` | `/advertisers/:advertiserId/testability` |

### Measurement sources

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/measurement-sources` |
| `POST` | `/advertisers/:advertiserId/measurement-sources` |
| `GET` | `/advertisers/:advertiserId/measurement-sources/:id` |
| `PATCH` | `/advertisers/:advertiserId/measurement-sources/:id` |

### Hypotheses

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/hypotheses` |
| `POST` | `/advertisers/:advertiserId/hypotheses` |
| `GET` | `/advertisers/:advertiserId/hypotheses/:id` |
| `PATCH` | `/advertisers/:advertiserId/hypotheses/:id` |
| `DELETE` | `/advertisers/:advertiserId/hypotheses/:id` |

### Test cohorts

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/test-cohorts` |
| `POST` | `/advertisers/:advertiserId/test-cohorts` |
| `GET` | `/advertisers/:advertiserId/test-cohorts/:id` |
| `PUT` | `/advertisers/:advertiserId/test-cohorts/:id` |
| `DELETE` | `/advertisers/:advertiserId/test-cohorts/:id` |

### Test plans

| Method | Path |
| - | - |
| `GET` | `/advertisers/:advertiserId/hypotheses/:hypothesisId/test-plans` |
| `POST` | `/advertisers/:advertiserId/hypotheses/:hypothesisId/test-plans` |
| `GET` | `/advertisers/:advertiserId/test-plans/:id` |
| `PATCH` | `/advertisers/:advertiserId/test-plans/:id` |
| `POST` | `/advertisers/:advertiserId/test-plans/:id/link-buys` |

## Related

> [card] [Conversion API](https://docs.apostra.com/v2/integrations/conversion-api.md)
>
> Send per-user purchase, lead, and engagement events with click and identity
> matching.

> [card] [Campaigns](https://docs.apostra.com/v2/object-guides/campaign.md)
>
> Set up the campaigns and media buys that measurement data attaches to.

> [card] [Authentication](https://docs.apostra.com/v2/authentication.md)
>
> Generate and manage API keys for measurement requests.

> [card] [Reporting](https://docs.apostra.com/v2/guides/reporting-overview.md)
>
> Pull aggregated performance once measurement data is flowing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.