Upload measurement records

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

POST /api/v2/buyer/advertisers/{advertiserId}/measurement-records Uploads outcome measurement records (sales, brand lift, etc.) directly to the learning engine. Each record carries a value for one outcome type, geo, and time window. Up to 5,000 records per call. Records upsert on (account, advertiser, outcomeType, source, geo, time window, campaignId, mediaBuyId, packageId). A record can name the campaign, media buy and package whose delivery it measures. Without them, the record is about the advertiser as a whole. With a mediaBuyId, the result belongs to that buy and its seller rather than to the whole campaign. A record’s value is the measured amount for its own time window, not a running total since an earlier date. To read cost per outcome for each package and day, upload one record per package per day: a record whose timeWindowStart and timeWindowEnd are the same day, naming mediaBuyId and packageId. See cost per outcome.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/measurement-records \
  -H "Authorization: Bearer $SCOPE3_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": "acme_incr_rev",
        "lagDays": 7
      }
    ]
  }'

Parameters

Field	Type	Required	Notes
`advertiserId`	string	Yes	Path parameter — the owning advertiser
`records`	array	Yes	1–5000 records
`records[].outcomeType`	string	Yes	Outcome being measured (e.g. `incremental_revenue`)
`records[].geo`	string	Yes	Geo identifier (e.g. `US-CA`)
`records[].timeWindowStart`	string	Yes	Date `YYYY-MM-DD`
`records[].timeWindowEnd`	string	Yes	Date `YYYY-MM-DD`
`records[].value`	number	Yes	Measured value
`records[].source`	string	Yes	Source key (matches a measurement source)
`records[].baselineValue`	number	No	Counterfactual baseline
`records[].confidenceInterval`	number	No	Confidence on the value
`records[].lagDays`	integer	No	Reporting lag in days
`records[].campaignId`	string	No	Campaign whose delivery the record measures. Must belong to this advertiser. Defaults to the media buy’s campaign when `mediaBuyId` is set
`records[].mediaBuyId`	string	No	Media buy whose delivery the record measures. Must belong to this advertiser, and to `campaignId` when both are set
`records[].packageId`	string	No	Package within `mediaBuyId` the record measures. Requires `mediaBuyId`

Response

{
  "recordsUpserted": 1,
  "records": [
    {
      "id": "mr_001",
      "advertiserId": "12345",
      "outcomeType": "incremental_revenue",
      "geo": "US-CA",
      "timeWindowStart": "2026-03-01",
      "timeWindowEnd": "2026-03-07",
      "value": 8450.75,
      "baselineValue": 7100.00,
      "confidenceInterval": 0.92,
      "source": "acme_incr_rev",
      "receivedAt": "2026-04-19T08:00:00Z",
      "lagDays": 7
    }
  ]
}

recordsUpserted is the number of records inserted or updated (records upsert on (account, advertiser, outcomeType, source, geo, time window, campaignId, mediaBuyId, packageId), so re-uploading the same key updates in place). records[] echoes the persisted rows, including campaignId, mediaBuyId and packageId when the record names them. Which campaign, media buy and package a record names is part of what identifies it. Records for the same outcome type, source, geo and time window that name different media buys or packages are stored as separate records, and each one is updated in place only by a later upload of exactly the same combination. A record that names no media buy describes the whole campaign (or the whole advertiser when it names no campaign either), and is kept alongside any per-buy records for the same window. A campaign, media buy or package that does not belong to this advertiser refuses the whole upload with VALIDATION_ERROR, naming the record (for example records[3].mediaBuyId). Nothing is stored.

Errors

400 VALIDATION_ERROR — empty records, more than 5,000 records, a missing required field, or a malformed timeWindowStart/timeWindowEnd date.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

Measurement tasks

All measurement operations

Measurement overview

Pipeline, belief state, and concepts

List measurement records

Query uploaded records

Upload context records

Add market conditions to partial out

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Upload measurement records

Request

Parameters

Response

Errors

Measurement tasks

Measurement overview

List measurement records

Upload context records

​Request

​Parameters

​Response

​Errors

​Related

Measurement tasks

Measurement overview

List measurement records

Upload context records

Request

Parameters

Response

Errors

Related