The publisher real-time API enables low-latency access to Scope3 classifications for an entire page and/or content artifacts adjacent to ad units, formatted for use through Google Ad Manager, Prebid, and other common ad tech services.

Retrieve Scope3 classifications

Page level classification

The RTAPI will respond with a list of key/value pairs for the page URL that can be passed into GAM, as well as an encrypted version of this data that can be safely passed into the programmatic ecosystem via header bidding for use in PMPs and curated deals.

Ad Unit level classification

For each ad unit on the page, the publisher provides a list of adjacent artifacts. For instance, in an infinite scroll, the adjacent content might be the two posts or articles above and below the ad slot. The RTAPI will respond with a list of key/value pairs for each ad slot that can be passed into GAM, as well as an encrypted version of this data that can be safely passed into the programmatic ecosystem via header bidding for use in PMPs and curated deals.

Inputs

The input to the RTAPI should be a JSON object (protobuf also supported).

Field	Value	Required
`url`	The URL of the page	✅ Required
`lastUpdateTime`	The datetime (in UTC timezone) when the content of the page was last updated - useful to help Scope3 know to re-classify the page since updates were made. Supported Formats: YYYYMMddThh:mm:ss.s, YYYYMMddThh:mm:ss, yyyy/mm/ddThh:mm:ss.s, yyyy/mm/ddThh:mm:ss, yyyy-mm-ddThh:mm:ss.s,yyyy-mm-ddThh:mm:ss
`ad_units`	An array of "AdUnit" objects (see below)
`uvec`	An array of user segments
`property_id`	The domain or app ID
`user_country`	The user's country (useful for avails and limiting KV response size)
`user_agent`	The browser user agent - useful for bot detection
`ip_address`	The user's IP address - useful for bot detection

AdUnit Object

Field	Value	Required
`id`	The ad unit ID - should be the same as configured in GAM	✅ Required
`adjacent_artifacts`	The list of artifact IDs that are adjacent to the ad unit	✅ Required
`transaction_id`	The ID of the ad impression - used for deduping avails as tracked via programmatic

Example

{
  "user_country": "US",
  "url": "http://bigpub.com/an-article",
  "url_last_updated": "2025-01-30T15:26:58",
  "ad_units":
	[
    {
      "id": "/rail/bigsky",
      "adjacent_artifacts": ["2723829183", "/truecrime/big-news-in-local-police"],
      "transaction_id": "12382200183"
    },
    {
      "id": "/takeover/full",
      "adjacent_artifacts": [],
      "transaction_id": "12382200221"
    }
  ]
}

Outputs

The RTAPI outputs a list of key-values for the page URL and/or each ad unit in the order that they were received, as well as an encrypted version of the same data that can be passed into the Scope3 prebid object.

Field	Value
`url_classifications`	Contains an array of key-values to pass to ad tech services
`ad_units_classifications`	Array of AdUnitClassificationsResponse objects (see below)
`scope3data`	Encrypted data sent via prebid

Example

{
 "url_classifications":
  {
    "keyvals":[
      {
       "key": "scope3_segs",
       "values": ["f1b", "b2j", "p8s"] 
      }
    ]
  },
  "ad_units_classifications":
  [
    {
      "id": "/rail/bigsky",
      "keyvals": [
        {
          "key": "scope3_segs",
          "values": ["f1b", "b2j", "p8s"]
        }
      ]
    }
  ],
  "scope3data": "asdfaflkasjlasdlfjasdfl88232asdfasdf..."
}

Private Endpoint (proposed)

Each publisher will be configured with a private endpoint that should be added to network configuration from the rendering servers. The endpoint URL will be provided as part of the setup process.

Metrics and Monitoring

Each publisher endpoint will have a /metrics endpoint that provides Prometheus-compatible metrics:

Metric	Type	Values
`requests`
`segments_returned`
`bespoke_profiles_active`	gauge
`standard_profiles_active`
`response_time_us`