Get measurement freshness

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.

GET /api/v2/buyer/advertisers/{advertiserId}/measurement-freshness Checks for gaps in measurement data coverage relative to a flight schedule and the registered source cadence. Run this during flight to confirm data is actually arriving for the geos and windows you expect. Only daily and weekly sources are checked. A weekly source expects one record per geo for each week from flightStart; a daily source expects one per geo for each day from flightStart through flightEnd. Each window is due lagWeeks after it ends: a weekly window after the start of its last day, a daily window at the end of the day. Sources carry lag in whole weeks only, so a daily source with lagWeeks: 1 flags a missing day one week after that day. Days are UTC days. Daily sources are checked for at most the last 366 days of the flight that are due; older days are not reported. Weekly sources are checked for every week of the flight. A weekly window counts as present when any record for the source’s outcomeType, that week’s start date and the geo exists. A daily window counts as present only when the record’s source is also the daily source’s sourceKey, so two sources that share an outcome type do not fill each other’s days. Upload daily records with source set to the source’s sourceKey. Sources with any other cadence, and sources with no window due yet, are listed in sourcesSkipped and not checked. Each reason starts with a stable code, unsupported_cadence: or no_window_due:, followed by a readable explanation; for no_window_due it says when the first window falls due.

Request

curl "https://api.apostra.com/api/v2/buyer/advertisers/12345/measurement-freshness?flightStart=2026-03-01&flightEnd=2026-04-30&geos=US-CA,US-OR,US-WA" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`advertiserId`	string	Yes	Path parameter — the owning advertiser
`flightStart`	string	Yes	Date `YYYY-MM-DD` start of the flight window
`flightEnd`	string	No	Date `YYYY-MM-DD` end of the flight window. Defaults to now
`geos`	string	Yes	Comma-separated geos to check coverage for

Response

{
  "status": "evaluated",
  "sourcesEvaluated": 1,
  "sourcesSkipped": [
    {
      "source": "acme_brand_survey",
      "cadence": "monthly",
      "reason": "unsupported_cadence: cadence \"monthly\" is not evaluated; only daily and weekly sources are checked."
    }
  ],
  "gaps": [
    {
      "source": "acme_orders",
      "sourceName": "Acme Orders",
      "outcomeType": "incremental_revenue",
      "cadence": "weekly",
      "lagWeeks": 1,
      "expectedWeekStart": "2026-04-01T00:00:00Z",
      "expectedWeekEnd": "2026-04-07T23:59:59Z",
      "geosMissing": ["US-WA"],
      "geosPresent": ["US-CA", "US-OR"],
      "daysOverdue": 12
    }
  ],
  "totalMissing": 1,
  "mostOverdue": {
    "source": "acme_orders",
    "sourceName": "Acme Orders",
    "outcomeType": "incremental_revenue",
    "cadence": "weekly",
    "lagWeeks": 1,
    "expectedWeekStart": "2026-04-01T00:00:00Z",
    "expectedWeekEnd": "2026-04-07T23:59:59Z",
    "geosMissing": ["US-WA"],
    "geosPresent": ["US-CA", "US-OR"],
    "daysOverdue": 12
  },
  "lastUploadDate": "2026-04-19T08:00:00Z",
  "baselineCoverage": {
    "weeksPresent": 7,
    "weeksExpected": 8,
    "geosPresent": 2,
    "geosExpected": 3
  }
}

Read status before totalMissing. A zero totalMissing means nothing is missing only when status is evaluated:

`status`	Meaning
`no_sources`	The advertiser has no measurement sources. Nothing is checked; `baselineCoverage` is `null`. Create a measurement source first.
`not_evaluated`	The advertiser has sources, but none was checked: none is `daily` or `weekly`, or none has a window due yet (for example, the flight started less than `lagWeeks` ago). Each one is listed in `sourcesSkipped` with the reason.
`evaluated`	At least one source was checked against at least one due window. `sourcesEvaluated` is how many. Any others are in `sourcesSkipped`.

gaps[] lists each source / window / geo combination where expected data has not arrived. For a daily source, expectedWeekStart and expectedWeekEnd are both the missing day. totalMissing is the number of missing geo-windows across gaps; mostOverdue is the single gap with the highest daysOverdue (or null when there are none). lastUploadDate is the most recent record received (or null), and baselineCoverage summarizes how many of the 52 weeks before flightStart have data for the first source, and in how many of the requested geos (or null when the advertiser has no sources).

Errors

400 VALIDATION_ERROR — missing flightStart or geos, or a malformed 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

Upload measurement records

Fill the gaps with outcome records

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Get measurement freshness

Request

Parameters

Response

Errors

Measurement tasks

Measurement overview

Upload measurement records

​Request

​Parameters

​Response

​Errors

​Related

Measurement tasks

Measurement overview

Upload measurement records

Request

Parameters

Response

Errors

Related