StackAdapt (GraphQL): Setup guide
On this page
This guide explains how to collect data from StackAdapt (GraphQL).
Introduction
StackAdapt is a programmatic advertising platform for native, display, video, CTV, audio, and digital out-of-home campaigns. The StackAdapt (GraphQL) connector uses the StackAdapt GraphQL API to collect campaign, ad, and advertiser delivery data, campaign insights broken down by attributes such as country, device, or audience, and ChatGPT ads performance data. You can also run your own GraphQL query.
Limitations
Collecting data from StackAdapt (GraphQL) comes with the following limitations:
-
Campaign Insights and ChatGPT Ads reports support only the Daily and Total granularities.
-
A Campaign Insights report with the Total granularity requires at least one attribute in Attributes.
-
Campaign Insights reports with the Total granularity do not contain a date column.
-
A Custom GraphQL Query reads data for all advertisers available to the API key. It runs only if all advertisers of the authorization are enabled, and you cannot restrict it to selected advertisers or campaigns.
-
StackAdapt prepares delivery and insight reports in the background. For long date ranges, a fetch can take longer while StackAdapt prepares the report.
Prerequisites
Before you start collecting data from StackAdapt (GraphQL), perform all of the following actions:
-
Obtain a StackAdapt GraphQL API key from StackAdapt support.
Creating a datastream to collect data from StackAdapt (GraphQL)
The basics of creating a datastream to collect data from any data source are explained in our guide to Collecting data in Adverity. This guide contains information about the specific steps to create a datastream to fetch data from StackAdapt (GraphQL).
Configuration: Choose the data you want to collect from StackAdapt (GraphQL)
To choose what data to collect and customize the StackAdapt (GraphQL) datastream configuration, follow these steps:
-
(Optional) Rename your datastream.
-
In Report type, select the type of data to collect from StackAdapt. The available options are:
-
Campaign Delivery — delivery metrics at the campaign level
-
Ad Delivery — delivery metrics at the ad level
-
Advertiser Delivery — delivery metrics at the advertiser level
-
Campaign Insights (default) — campaign metrics broken down by the selected attributes
-
ChatGPT Ads — performance metrics of your ChatGPT ads
-
Custom GraphQL Query — the result of a GraphQL query you write
The selected report type determines the additional fields to populate.
-
-
If you selected any report type except Custom GraphQL Query, in Advertisers, select the advertisers from which to collect data. If left as All, data for all advertisers is retrieved.
-
If you selected Campaign Delivery, Ad Delivery, or Campaign Insights, (Optional) in Campaigns, select the campaigns from which to collect data. If left empty, data for all campaigns is retrieved.
-
If you selected Campaign Insights, in Attributes, select one or more attributes to break the campaign insights down by, for example Country (default), Device type, or Audience.
-
If you selected any report type except Custom GraphQL Query, in Fields, select the columns to include in your data extract. The available fields depend on the selected report type. If left empty, the default fields of the selected report are retrieved.
-
If you selected any report type except Custom GraphQL Query, in Granularity, select the time granularity of the data:
-
Campaign Delivery, Ad Delivery, and Advertiser Delivery — Hourly, Daily (default), Weekly, Monthly, or Total
-
Campaign Insights and ChatGPT Ads — Daily or Total (default)
Total returns one row per item for the whole fetched date range.
-
-
If you selected ChatGPT Ads, (Optional) clear Include archived ads to leave archived ads out of the data extract. By default, archived ads are included.
-
If you selected Custom GraphQL Query, in GraphQL query, enter the GraphQL query to run. For more information, see Writing a custom GraphQL query.
As a result, Adverity fetches data from StackAdapt (GraphQL) according to the configuration you set.
What’s next?
-
Apply Data Mapping to your collected data to harmonize data collected from different sources in Adverity.
-
Transform your data to meet your needs by creating and applying transformations to your datastream.
-
Load your data into a warehouse to continue working with your data in Adverity.
-
Load your data into an external destination of your choice.
Advanced StackAdapt (GraphQL) tips
Writing a custom GraphQL query
With the Custom GraphQL Query report type, you can query any data available in the StackAdapt GraphQL API. Adverity checks the query against the StackAdapt GraphQL schema when you save the datastream.
When writing the query, consider the following:
-
Request only the data you need, keep the query simple, and minimize field nesting.
-
To use the fetch date range in the query, declare the
$dt_startand$dt_endvariables asISO8601DateorISO8601DateTime. Adverity fills them with the start and end of the fetched date range. -
To collect more than one page of results, declare the
$cursorvariable, pass it as theafterargument, and requestpageInfowithendCursorandhasNextPage. -
For delivery and insight reports, request
__typenameon the report so that Adverity can wait until StackAdapt has prepared the report.
The following example query collects daily campaign delivery data:
query($dt_start: ISO8601Date!, $dt_end: ISO8601Date!, $cursor: String) {
campaignDelivery(dataType: TABLE, granularity: DAILY, date: {from: $dt_start, to: $dt_end}) {
__typename
... on CampaignDeliveryOutcome {
records(first: 500, after: $cursor) {
nodes {
campaign { id name }
metrics { impressionsBigint clicksBigint cost }
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
}