Skip to main content

Stackadapt API Connector

Updated over a week ago
For the Press | StackAdapt

Overview

This document provides a comprehensive guide for integrating and managing StackAdapt data imports, including connection setup, import scheduling, required user inputs, table structures, relationships, and available reporting dimensions and metrics. The configuration is designed to automate the retrieval and refresh of both delivery and metadata from the StackAdapt platform, enabling robust analytics and reporting.

Connection Setup / Requirements

To connect to the StackAdapt platform, the following credentials and parameters are required:

Parameter

Description

Required

Type

Max Length

StackAdapt API Key

API Key generated in the StackAdapt UI for authentication.

Yes

Text

30

StackAdapt Advertiser ID

Numeric Advertiser ID found in the StackAdapt UI to specify data scope.

Yes

Text

30

Note:

Ensure your API key is active and has the necessary permissions for data access.

The Advertiser ID filters the data imported to only the specified advertiser.

Import Configuration

Two primary jobs are defined for data ingestion:

1. Delivery Data Import

  • Feed: stackadapt

  • Job Label: StackAdapt - Data Import

  • Status: Enabled (1)

  • Targets:

    • stackadapt_data_aggregate (Data table)

      • Update Mode: Append (new data is added)

      • Create Target: True (table auto-created if missing)

      • Date Column: date

    • stackadapt_data_conversions (Data table)

      • Update Mode: Append

      • Create Target: True

      • Date Column: date

  • Lookback: 5 days

  • First Run Hour: 06:00 UTC

  • Poll Frequency: Every 24 hours

2. Metadata Refresh

  • Feed: stackadapt

  • Job Label: StackAdapt - Meta Refresh

  • Status: Enabled (1)

  • Targets:

    • stackadapt_meta_advertiser (Lookup table) - method: advertisers

    • stackadapt_meta_campaign (Lookup table) - method: campaigns

    • stackadapt_meta_nativeads (Lookup table) - method: native_ads

    • stackadapt_meta_lineitem (Lookup table) - method: lineitems

    • stackadapt_meta_trackers (Lookup table) - method: trackers

  • Update Mode: Refresh (full table refresh)

  • Create Target: True

  • Lookback: 1 day

  • First Run Hour: 06:00 UTC

  • Poll Frequency: Every 24 hours

Import Schedule

Job

Poll Frequency (hours)

Lookback

First Run Hour (UTC)

Delivery Import

24

5 days

06:00

Meta Refresh

24

1 day

06:00


  • Poll Frequency: How often the import job runs.

  • Lookback: Number of days of data fetched on each run.

Required User Input

Before running the integration, users must provide in connection settings:

  • StackAdapt API Key – for authentication.

  • StackAdapt Advertiser ID – numeric ID for filtering data.

Both are mandatory.

Tables Created

The integration creates and populates the following tables:

Table Name

Description

Type

Update Mode

stackadapt_data_aggregate

Delivery Data

Data

Append

stackadapt_data_conversions

Conversions Data

Data

Append

stackadapt_meta_advertiser

Advertiser Metadata

Lookup

Refresh

stackadapt_meta_campaign

Campaign Metadata

Lookup

Refresh

stackadapt_meta_nativeads

Native Ads Metadata

Lookup

Refresh

stackadapt_meta_lineitem

Line Item Metadata

Lookup

Refresh

stackadapt_meta_trackers

Tracker Metadata

Lookup

Refresh

All tables are automatically created if they do not exist.

Table Relationships

Delivery and conversion data tables link to metadata tables using the following keys:

Key in Data Table

Linked Metadata Table

Metadata Table Key

campaign_id

stackadapt_meta_campaign

id

native_ad_id

stackadapt_meta_nativeads

id

sub_advertiser_id

stackadapt_meta_advertiser

id

line_item_id

stackadapt_meta_lineitem

id

id (in conversions data)

stackadapt_meta_trackers

id

These joins enable enriched reporting by linking detailed delivery and conversion data with associated metadata.

Available Dimensions

Dimension Name

Result Fields

Description

Advertiser [StackAdapt]

stackadapt_meta_advertiser.name

Name of the advertiser account in StackAdapt

Campaign [StackAdapt]

stackadapt_meta_campaign.name

Name of the associated campaign

Line Item [StackAdapt]

stackadapt_meta_lineitem.name

Name of the line item

Ads [StackAdapt]

stackadapt_meta_nativeads.name

Name of the native ad

Tracker [StackAdapt]

stackadapt_meta_trackers.name

Name of the tracker

Available Metrics

Base Metrics

Metric Name

Formula / Calculation

Round

Description

Impressions [StackAdapt]

SUM({stackadapt_data_aggregate.imp})

0

Total impressions served

Clicks [StackAdapt]

SUM({stackadapt_data_aggregate.click})

0

Total clicks received

Spend [StackAdapt]

SUM({stackadapt_data_aggregate.cost}) + SUM({stackadapt_data_conversions.cost})

2

Total media spend in GBP

Revenue [StackAdapt]

SUM({stackadapt_data_aggregate.revenue}) + SUM({stackadapt_data_conversions.revenue})

2

Total revenue generated

Video Starts [StackAdapt]

SUM({stackadapt_data_aggregate.vcomp_0})

0

Number of video start events

Video 25% Completions [StackAdapt]

SUM({stackadapt_data_aggregate.vcomp_25})

0

Number of times video reached 25% completion

Video 50% Completions [StackAdapt]

SUM({stackadapt_data_aggregate.vcomp_50})

0

Number of times video reached 50% completion

Video 75% Completions [StackAdapt]

SUM({stackadapt_data_aggregate.vcomp_75})

0

Number of times video reached 75% completion

Video Completes [StackAdapt]

SUM({stackadapt_data_aggregate.vcomp_95})

0

Number of times video reached 95% (complete)

Conversions [StackAdapt]

SUM({stackadapt_data_aggregate.conv}) + SUM({stackadapt_data_conversions.conv})

0

Total conversions attributed

Conversion Clicks [StackAdapt]

SUM({stackadapt_data_conversions.conv_click})

0

Conversions attributed from clicks

Conversion Cookie [StackAdapt]

SUM({stackadapt_data_conversions.conv_cookie})

0

Conversions attributed via cookie tracking

Conversion IP [StackAdapt]

SUM({stackadapt_data_conversions.conv_ip})

0

Conversions attributed via IP tracking

Conversion Derived from Impression [StackAdapt]

SUM({stackadapt_data_conversions.conv_imp_derived})

0

Conversions attributed as derived from impression

Composite Metrics

Metric Name

Formula

Round

Prefix

Suffix

Description

CTR [StackAdapt]

({Clicks [StackAdapt]} / {Impressions [StackAdapt]}) * 100

2

%

Click Through Rate

CPC [StackAdapt]

{Spend [StackAdapt]} / {Clicks [StackAdapt]}

2

£

Cost per Click

CPV [StackAdapt]

{Spend [StackAdapt]} / {Video Starts [StackAdapt]}

2

£

Cost per Video Start

CPCV [StackAdapt]

{Spend [StackAdapt]} / {Video Completes [StackAdapt]}

2

£

Cost per Completed Video View

VCR [StackAdapt]

({Video Completes [StackAdapt]} / {Video Starts [StackAdapt]}) * 100

2

%

Video Completion Rate

VTR [StackAdapt]

({Video Completes [StackAdapt]} / {Impressions [StackAdapt]}) * 100

2

%

Video Through Rate (completes per impression)

Conversion Rate [StackAdapt]

({Conversions [StackAdapt]} / {Clicks [StackAdapt]}) * 100

2

%

Conversion Rate

Revenue per Click [StackAdapt]

{Revenue [StackAdapt]} / {Clicks [StackAdapt]}

2

£

Average revenue per click

ROI [StackAdapt]

(({Revenue [StackAdapt]} - {Spend [StackAdapt]}) / {Spend [StackAdapt]}) * 100

2

%

Return on Investment

Additional Information

  • The integration is designed for daily batch imports.

  • All tables and columns are automatically created if they do not exist.

  • You can request additional fields or metrics by contacting support with your requirements.

Additional Fields

This section documents extra fields available in the StackAdapt tables beyond the primary metrics. These fields provide greater detail and enable more in-depth analysis.

Aggregate Table Fields (stackadapt_data_aggregate)

Field Name

Description

Data Type

50v_2s_ias

Number of impressions lasting at least 2 seconds (IAS metric)

Integer

acomp_0

Number of video ad completions at 0%

Integer

acomp_25

Number of video ad completions at 25%

Integer

acomp_50

Number of video ad completions at 50%

Integer

acomp_75

Number of video ad completions at 75%

Integer

acomp_95

Number of video ad completions at 95%

Integer

atos

Average time on site (seconds)

Float

atos_units

Units for average time on site (usually seconds)

Float

campaign

Name of the campaign

String

campaign_id

Unique identifier of the campaign

Integer

campaign_type

Type of the campaign (e.g. native)

String

channel

Advertising channel (e.g. display)

String

click

Number of clicks

Integer

click_cvr

Click conversion rate

Float

click_url

URL used for clicks

String

conv

Number of conversions

Integer

conv_click

Number of conversions attributed to clicks

Integer

conv_cookie

Number of conversions attributed via cookie tracking

Integer

conv_imp_derived

Number of conversions derived from impressions

Integer

conv_imp_time_avg

Average time (ms) between impression and conversion

Float

conv_ip

Number of conversions attributed via IP tracking

Integer

conv_rev

Conversion revenue

Float

cost

Total cost (usually in GBP)

Float

creatives_0_size

Size of the primary creative (e.g. 160x600)

String

ctr

Click-through rate

Float

cvr

Conversion rate

Float

date

Date of the data record (YYYY-MM-DD)

Date/String

ecpa

Effective cost per acquisition

Float

ecpc

Effective cost per click

Float

ecpcl

Effective cost per lead

Float

ecpe

Effective cost per engagement

Float

ecpm

Effective cost per thousand impressions

Float

ecpv

Effective cost per view

Float

end_date

End date/time in ISO 8601 format

DateTime/String

engage_rate

Engagement rate

Integer/Float

ga4_average_session_duration

GA4 average session duration

Integer/Float

ga4_bounce_rate

GA4 bounce rate

Integer/Float

ga4_engaged_sessions

Number of GA4 engaged sessions

Integer

ga_avg_time

Google Analytics average session time

Integer/Float

ga_bounce_rate

Google Analytics bounce rate

Integer/Float

ga_goal_conversion_rate

Google Analytics goal conversion rate

Integer/Float

heading

Campaign or creative heading (optional)

String/Null

id

Numeric identifier for the advertiser or sub-advertiser

Integer

imp

Number of impressions

Integer

imp_cvr

Impression conversion rate

Float

line_item

Name of the line item

String

line_item_id

ID of the line item

Integer

ltr

Likelihood to respond indicator

Integer

measure_ias

Number of IAS measured impressions

Integer

native_ad_id

ID of the associated native ad

Integer

native_ad_type

Type of native ad (e.g. display)

String

nativead

Name of the native ad

String

page_start

Number of page start events

Integer

page_time

Total time spent on page (seconds)

Integer

page_time_15s

Number of page visits lasting at least 15 seconds

Integer

page_time_units

Units for page time (usually seconds)

Integer

profit

Profit amount

Float

rcpa

Revenue cost per acquisition

Float

rcpc

Revenue cost per click

Float

rcpcl

Revenue cost per lead

Float

rcpe

Revenue cost per engagement

Float

rcpm

Revenue cost per thousand impressions

Float

rcpv

Revenue cost per view

Float

revenue

Total revenue

Float

roas

Return on ad spend

Float

s_conv

Secondary conversions

Integer

sconv_click

Secondary conversions from clicks

Integer

sconv_imp

Secondary conversions from impressions

Integer

start_date

Start date/time in ISO 8601 format

DateTime/String

sub_advertiser_id

ID of the sub-advertiser

Integer

tagline

Campaign or creative tagline (optional)

String/Null

tp_cpc_cost

Third party cost per click

Float

tp_cpm_cost

Third party cost per thousand impressions

Float

uniq_conv

Number of unique conversions

Integer

unique_imp

Number of unique impressions

Integer

unique_imp_inverse_rate

Inverse rate of unique impressions

Float

user_id

User identifier

Integer

vcomp_0

Video completions at 0%

Integer

vcomp_25

Video completions at 25%

Integer

vcomp_50

Video completions at 50%

Integer

vcomp_75

Video completions at 75%

Integer

vcomp_95

Video completions at 95%

Integer

vcomp_rate

Video completion rate

Float

view_percent

Percent of video viewed

Float

sub_advertiser

Name of the sub-advertiser

String

Conversions Data Fields (stackadapt_data_conversions)

Field Name

Description

Data Type

atos

Average Time on Site (seconds)

Float

atos_units

Units for Average Time on Site

Float

click

Number of clicks

Integer

click_cvr

Click conversion rate

Float

conv

Number of conversions

Integer

conv_click

Number of conversions from clicks

Integer

conv_click_time_avg

Average time (seconds or ms) between click and conversion

Float

conv_cookie

Conversions attributed via cookie tracking

Integer

conv_imp_derived

Conversions derived from impressions

Integer

conv_imp_time_avg

Average time between impression and conversion

Float

conv_ip

Conversions attributed via IP tracking

Integer

cost

Cost associated with conversions

Float

ctr

Click-through rate

Float

cvr

Conversion rate

Float

date

Date of record

Date (YYYY-MM-DD)

ecpa

Effective cost per acquisition

Float

ecpc

Effective cost per click

Float

ecpcl

Effective cost per lead

Float

ecpe

Effective cost per engagement

Float

ecpm

Effective cost per mille

Float

ecpv

Effective cost per view

Float

imp

Number of impressions

Integer

imp_cvr

Impression conversion rate

Float

ltr

Likely to respond indicator

Integer

page_time

Time spent on page (seconds)

Integer

page_time_units

Units for page time

Integer

profit

Profit associated with conversions

Float

rcpa

Revenue cost per acquisition

Float

rcpc

Revenue cost per click

Float

rcpcl

Revenue cost per lead

Float

rcpe

Revenue cost per engagement

Float

rcpm

Revenue cost per mille

Float

rcpv

Revenue cost per view

Float

revenue

Revenue associated with conversions

Float

s_conv

Secondary conversions

Integer

tp_cpc_cost

Third-party cost per click

Float

tp_cpm_cost

Third-party cost per mille

Float

uniq_conv

Number of unique conversions

Integer

tracker_conv

Name of conversion tracker

String

id

Record unique identifier

Integer

Metadata Tables Additional Fields

Advertiser Dimensional Fields (stackadapt_meta_advertiser)

Field Name

Description

Data Type

id

Unique identifier for the advertiser

Integer

name

Name of the advertiser

String

description

Description of the advertiser (optional)

String (may be empty)

user_id

Identifier for the user associated with this advertiser

Integer

conv_type

Conversion attribution type (e.g., "imp" for impression-based)

String

post_time

Post time for data (may be blank/null)

String or Null

count_type

Count type indicator (e.g., "once")

String

Line Item Dimensional Fields (stackadapt_meta_lineitem)

Field Name

Description

Data Type

id

Unique identifier for the line item

Integer

name

Name of the line item

String

state

State or status of the line item (may be empty/null)

String or Null

daily_cap

Daily spending or impression cap (may be empty/null)

Integer, Float, or Null

pace_evenly

Indicator if pacing is evenly distributed (1 = true, 0 = false)

Boolean (Integer)

black_list_options

Blacklist options applied to the line item (may be empty/null)

String or Null

revenue_type

Type of revenue associated with the line item (may be empty/null)

String or Null

revenue_value

Revenue amount/value associated with the line item (may be empty/null)

Float or Null

purchase_order_number

Purchase order number associated with the line item (optional)

String or Null

all_campaign_ids_0

ID of an associated campaign

Integer

all_campaign_ids_1

ID of an associated campaign

Integer

all_campaign_ids_2

ID of an associated campaign

Integer

advertiser_id

ID of the advertiser this line item is associated with

Integer

status_code

Status code describing the line item state

String

status_description

Description of the line item’s status

String

start_date

Start date of the line item (ISO 8601 format)

Date (YYYY-MM-DD)

end_date

End date of the line item (ISO 8601 format)

Date (YYYY-MM-DD)

budget

Budget allocated for the line item

Float

Campaign Dimensional Fields (stackadapt_meta_campaign)

Field Name

Description

Data Type

id

Unique identifier of the campaign

Integer

line_item_id

Identifier of associated line item

Integer

name

Name of the campaign

String

bid_type

Type of bid (e.g., cpm, cpc)

String

bid_amount_total

Total bid amount

Float/Integer

pace_evenly

Whether pacing is evenly distributed (nullable)

Boolean/Null

state

Current state of campaign (e.g., active, paused)

String

created_at

Campaign creation datetime (ISO 8601 format)

DateTime/String

updated_at

Campaign last update datetime (ISO 8601 format)

DateTime/String

ip_options

IP targeting options (if any)

String/Null

use_dma

DMA targeting flag (if any)

Boolean/Null

allow_iframe_engagement

Whether iframe engagement is allowed

Boolean/Null

engagement_tracking_type

Numeric engagement tracking type

Integer

city_options

City targeting options

String/Null

timezone

Timezone of campaign targeting

String

is_deal_id_strict

Strict deal ID matching flag

Boolean/Null

weekday_enabled

Whether weekday targeting is enabled

Boolean/Null

advertiser_id

Identifier for the advertiser

Integer

start_date

Campaign start date (YYYY-MM-DD)

Date/String

status_code

Status code describing campaign state

String

status_description

Description of the current campaign status

String

end_date

Campaign end date (YYYY-MM-DD)

Date/String

channel

Campaign channel (e.g., display, video)

String

campaign_type

Type of campaign (e.g., display, video)

String

budget

Campaign budget amount

Float

daily_cap

Daily budget cap

Integer/Float/Null

day_part_enabled

Whether day part targeting is enabled

Boolean/Null

optimize_type

Optimization metric (e.g., ctr, cpc)

String

optimize_value

Target value for optimization

Float

domain_action

Domain filtering action (e.g., exclude or include)

String

geo_radius_targeting

Geo radius targeting data (typically JSON or null)

JSON/Null

Native Ads Dimensional Fields (stackadapt_meta_nativeads)

Field Name

Description

Data Type

id

Unique identifier for the native ad

Integer

name

Name of the native ad

String

audit_status

Audit status of the ad

String

state

Current state of the ad (e.g., active, paused)

String

created_at

Timestamp when the ad was created (ISO 8601 format)

DateTime (ISO 8601)

updated_at

Timestamp when the ad was last updated (ISO 8601 format)

DateTime (ISO 8601)

click_url

URL users are directed to when clicking the ad

String

brandname

Brand name associated with the ad

String

cta_text

Call-to-action text displayed on the ad (may be empty)

String / Null

channel

Advertising channel (e.g., display, native, video)

String

status_code

Status code describing the campaign status related to the ad

String

status_description

Human-readable description of the status

String

input_data_heading

Optional heading text for the ad (may be empty)

String / Null

input_data_tagline

Optional tagline text for the ad (may be empty)

String / Null

input_data_landing_url

Optional landing URL for the ad (may be empty)

String / Null

input_data_display_js_creative_0_width

Width in pixels of the primary JS creative

Integer

input_data_display_js_creative_0_height

Height in pixels of the primary JS creative

Integer

input_data_display_js_creative_0_js_code

Raw JavaScript/HTML code snippet for ad creative

String (HTML)

input_data_display_js_creative_0_is_expandable

Boolean flag indicating if the JS creative is expandable

Boolean

input_data_display_js_creative_0_js_code_macro

Macro-enabled version of the JS creative code

String (HTML)

icon

Icon or image URL related to the ad (may be empty)

String / Null

Conversion Tracker Dimensional Fields (stackadapt_meta_trackers)

Field Name

Description

Data Type

id

Unique identifier for the conversion tracker

Integer

name

Name of the conversion tracker

String

description

Description of the conversion tracker (optional)

String / Null

user_id

Identifier for the user associated with this tracker

Integer

conv_type

Type of conversion attribution (e.g., "imp" for impression-based)

String

post_time

Post time for data (may be empty or null)

String / Null

count_type

Counting method or frequency indicator (e.g., "once")

String

Did this answer your question?