Segment Activations

Activation is the process of pushing classified audience segments from your AudienceGPT library to demand-side platforms (DSPs) where they become available for ad targeting. AudienceGPT supports activation to LiveRamp, Trade Desk, Index Exchange, and custom API platforms. Once activated, segments are monitored through the Destinations dashboard, which tracks delivery health, detects stale segments, and provides an activity feed of all delivery events.

Activation Overview

The activation workflow follows this sequence:

1. Set up an outbound connection with platform credentials and configuration
2. Select segments from your library for activation
3. Configure the push (output template, CPM pricing)
4. Execute the push, which sends segments to the DSP page by page
5. Monitor delivery status on the Destinations dashboard
6. Maintain activations over time -- refresh stale segments, deactivate retired ones

Outbound Connection → Select Segments → Configure Push
  → Create Run + Pending Activations
  → Loop: Push Batch to Platform → Poll Status
  → Destinations Dashboard → Health Monitoring

Setting Up Outbound Connections

Each DSP platform requires an outbound connection with platform-specific credentials and configuration. See Platform Connections for the full connection creation guide. Below are the key setup considerations for each supported platform.

LiveRamp (OAuth2)

LiveRamp uses OAuth2 client credentials for authentication. When you create a LiveRamp outbound connection, AudienceGPT stores your service account credentials and automatically manages token acquisition and refresh.

Setup steps:

1. Navigate to the Activate page (/activate) and click New Connection
2. Select LiveRamp as the platform and Outbound as the direction
3. Enter your LiveRamp service account credentials:
   • Username -- your LiveRamp service account username
   • Password -- your LiveRamp service account password
   • Client ID -- the OAuth2 client ID from your LiveRamp developer portal
   • Organization ID -- your LiveRamp organization identifier
4. Configure platform settings:
   • Token URL -- defaults to the standard LiveRamp token endpoint
   • API Base URL -- defaults to https://api.liveramp.com
   • Default CPM -- the default cost-per-thousand for segments activated through this connection
   • Currency -- pricing currency (e.g., USD)
   • Data Source Location -- your LiveRamp data source location identifier
5. Click Save Connection, then Test Connection to verify credentials

info

LiveRamp OAuth2 tokens are automatically refreshed 60 seconds before expiry. You do not need to manually manage token lifecycle. If a token refresh fails during an activation, the error is logged and the affected segment can be retried.

Trade Desk

Trade Desk uses API key authentication with the Trade Desk Taxonomy Partner API.

Setup steps:

1. Create a new outbound connection with Trade Desk as the platform
2. Enter your Trade Desk credentials:
   • API Key -- your Trade Desk partner API key
   • Provider ID -- your provider identifier in the Trade Desk system
   • Brand ID (optional) -- for Data Alliance connections, the brand identifier (e.g., "dav2delvrai")
3. Configure platform settings:
   • API Base URL -- defaults to https://partners.thetradedesk.com/api/v3
   • Default CPM -- default cost-per-thousand
   • Currency -- pricing currency
4. Save and test the connection

Index Exchange (SFTP/S3)

Index Exchange supports two delivery methods: SFTP file upload and S3 bucket delivery. Segments are formatted as files with accompanying metadata and uploaded to the appropriate location based on match key type.

Setup steps:

1. Create a new outbound connection with Index Exchange as the platform
2. Choose your delivery method:
   • SFTP: Enter SFTP Host, Username, Password, and optionally Port (defaults to 22)
   • S3: Provide S3 Bucket name and IAM Role ARN
3. Configure Index Exchange-specific settings:
   • Account ID -- your IX account ID (appears as ownerAccount_id in meta files)
   • Advertiser Account ID -- advertiser identifier for meta files
   • Match Key -- determines the upload folder and data format. Options: ip, url, deviceid, uid, appbundle, contentid, postalcode
   • Default CPM -- default cost-per-thousand
   • Currency -- pricing currency
4. Save and test the connection

tip

The match key determines which SFTP directory your segment files are uploaded to. Ensure your match key aligns with the identifier type in your audience data. Using the wrong match key will result in files being placed in the wrong directory and may cause processing failures on the Index Exchange side.

Custom API

For platforms not natively supported, create a Custom API outbound connection with your platform's API details, authentication, and any required headers. Custom API connections follow the same push workflow but require you to ensure API compatibility.

Selecting Segments for Activation

Once your outbound connection is configured and tested, you can select segments from your library to activate.

From the Activate Page

1. Navigate to the Activate page (/activate)
2. Select your outbound connection from the connections panel
3. The segment selector displays your library topics, showing:
   • Topic name
   • Parent category and taxonomy type
   • Segment type (B2B/B2C)
   • Engine version
   • Current activation status (if previously activated on this connection)
4. Use checkboxes to select the segments you want to activate
5. Topics already active on the selected connection are shown with an "Active" badge and cannot be re-selected (refresh or deactivate them instead)

Segment Eligibility

Not all library topics can be activated. A topic must have:

• A valid classification (all 7 layers complete)
• A generated platform segment name for the target platform
• No blocking errors from previous activation attempts

Topics that do not meet these criteria appear grayed out with an explanation of why they cannot be activated.

Push Configuration and Execution

Output Templates

Each outbound connection has an associated output template that controls how segment names and descriptions are formatted for the target platform. Built-in templates include:

Template	Format	Character Limits
Trade Desk (Koa)	Taxonomy path with IAB code prefix	Name: 255 chars, Description: 1000 chars
LiveRamp	Hierarchical segment name with audience type	Name: 255 chars, Description: 500 chars
Internal	Full taxonomy path for internal reference	No limits

Custom output templates can be created by administrators with configurable Handlebars-style placeholders (e.g., {{parent_category}}, {{topic_name}}, {{user_behavior}}).

CPM Pricing

Each activation carries a CPM (cost-per-thousand) value that is sent to the DSP along with the segment data. The CPM defaults to the connection's configured default_cpm but can be overridden per push operation if the platform supports it.

Executing the Push

1. After selecting segments and confirming the configuration, click Push Selected
2. AudienceGPT creates a push run and pending activation records for each selected segment
3. Segments are pushed to the platform in batches of 25
4. For each segment, AudienceGPT:
   • Generates the platform-specific name and description using the output template
   • Calls the platform's create segment API (or update, if refreshing an existing activation)
   • Records the platform's segment ID, pushed name, and engine version
   • Updates the activation status to "Active" on success or "Error" on failure
5. Progress is displayed in real time with counts of successful, failed, and skipped segments

warning

Push operations make live changes on external DSP platforms. Each successful push creates or updates a real segment that buyers can target. Verify your segment selection and output template formatting before executing a push.

Retry Behavior

If a segment fails to push, AudienceGPT retries up to 3 times with exponential backoff. After all retries are exhausted, the activation is marked with an error status and the error message is recorded. You can retry failed activations individually from the activation detail view.

Activation Management

Viewing Activations

Your activations are accessible from two locations:

• Activate page (/activate): Lists activations grouped by outbound connection, showing status, platform segment ID, pushed name, and timestamps
• Destinations dashboard (/destinations): Provides a health-focused view of all activations across all connections

Each activation record tracks:

Field	Description
Status	Draft, Pending, Active, Deactivated, or Error
Platform Segment ID	The ID assigned by the DSP after successful creation
Pushed Name	The segment name that was sent to the platform
Pushed Description	The segment description that was sent to the platform
Engine Version at Push	The classification engine version when the segment was pushed
Push Attempts	Number of push attempts (including retries)
Activated At	Timestamp of successful activation
Error Message	Error details if the activation failed

Refreshing Activations

When a topic's classification is updated (e.g., after reclassification or an engine version upgrade), its activated segments may become stale. Refreshing an activation pushes the updated segment name and description to the DSP.

Individual refresh:

1. Navigate to the activation detail (from the Activate page or Destinations dashboard)
2. If the activation is stale, a Refresh button appears
3. Click Refresh to push the updated data to the platform

Batch refresh: Use the Refresh All Stale button on the Data Hygiene dashboard to refresh all stale activations across all connections in a single background job.

Deactivating Segments

To remove a segment from a DSP platform:

1. Navigate to the activation detail
2. Click Deactivate
3. AudienceGPT calls the platform's deactivation API to remove or disable the segment
4. The activation status changes to "Deactivated" with a timestamp

Deactivated segments remain in your activation history for auditing purposes but are no longer active on the DSP. You can re-activate a deactivated segment by creating a new push that includes it.

info

Deactivation behavior varies by platform. LiveRamp marks the segment as inactive in their system. Trade Desk removes it from the taxonomy. Index Exchange depends on the file-based delivery process -- consult Index Exchange documentation for their deactivation workflow.

Destinations Dashboard

The Destinations dashboard at /destinations provides a unified monitoring view of all your outbound connections and their activated segments. It is the primary tool for understanding the health and delivery status of your activated audience data.

Health Indicators

Each outbound connection on the dashboard displays a health indicator based on the aggregate state of its activations:

Indicator	Condition	What It Means
Healthy (green)	All activations are active, none stale, no errors	Everything is running smoothly -- all segments are up to date on the DSP
Stale (yellow)	One or more activations have diverged from current topic data	Segments on the DSP have outdated names or classifications -- refresh recommended
Errors (red)	One or more activations failed or have error status	Some segments could not be pushed -- investigate error messages and retry
Idle (gray)	The connection has no activations	No segments have been pushed through this connection yet

Connection Overview Cards

The dashboard displays one card per outbound connection, showing:

• Connection name and platform badge (LiveRamp, Trade Desk, Index Exchange, Custom API)
• Health indicator with color coding
• Active segments count -- number of successfully activated segments
• Stale segments count -- segments needing refresh
• Error segments count -- segments in error state
• Last push timestamp -- when the most recent push operation occurred

Activity Feed

Below the connection cards, the activity feed displays a chronological timeline of all delivery events across your connections. Each event includes a timestamp, event type, connection name, and a summary description.

Event types tracked in the activity feed:

Event Type	Description
Push Started	A push run was initiated
Push Completed	A push run finished successfully
Push Failed	A push run encountered a fatal error
Push Cancelled	A push run was cancelled by the user
Segment Activated	An individual segment was successfully activated on the DSP
Segment Deactivated	A segment was removed from the DSP
Segment Refreshed	A stale segment was updated on the DSP
Segment Error	An individual segment activation failed
Stale Detected	The system detected that an activation has become stale
Connection Tested	A connection test was performed
Connection Created	A new outbound connection was configured
Connection Updated	Connection settings were modified
Connection Deleted	A connection was removed

Destination Detail View

Click on any connection card to open the detail view, which shows:

• Full activation list with status, platform segment ID, pushed name, and engine version
• Stale activations highlighted with a refresh button
• Error activations with error messages and retry buttons
• Connection configuration summary (platform, CPM, template)
• Push history -- past push runs with per-run statistics (success, error, skip counts)

Stale Detection

AudienceGPT continuously evaluates whether activated segments are stale by comparing two attributes at read time:

1. Pushed name vs. current name: The segment name sent to the DSP at activation time is compared against the name the topic currently produces using the connection's output template. If your output template has changed, or the topic was reclassified with different taxonomy placement, the names will diverge.

2. Engine version at push vs. current engine version: The engine version stamped on the activation record is compared to the topic's current engine version. If the classification engine has been updated since the push, the activation is considered stale.

An activation is flagged as stale if either condition is true. Stale activations appear in:

• The Destinations dashboard with a yellow health indicator on the affected connection
• The Data Hygiene dashboard under the Stale Activations card
• The activation detail view with a prominent Refresh button

tip

Monitor your Destinations dashboard regularly, especially after engine version upgrades or output template changes. These are the two most common causes of stale activations. A quick batch refresh from the hygiene dashboard brings everything up to date.

Next Steps

• Data Hygiene -- Batch refresh stale activations and monitor overall data health
• Platform Connections -- Add or modify outbound connections for new DSP platforms
• Topic Catalog -- Browse and add topics to your library before activating them