Skip to content
Book a demo

Connect documentation

All documentation
Documentation

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).

Authorization: Allow Adverity to access StackAdapt (GraphQL)

To set up a new authorization to fetch data from StackAdapt (GraphQL), follow these steps:

  1. In the Authorization step of the datastream wizard, click Access StackAdapt (GraphQL) using your credentials.

  2. Click Next.

  3. In API Key, enter your StackAdapt GraphQL API key.

  4. Click Authorize.

  5. For the Advertisers account type, if you choose Access using your credentials or Access using someone else's credentials, in Set up or edit Advertisers, you or the person granting access must choose one of the following options:

    • Choose Grant access to all items, including those created in the future to give Adverity permission to access all existing advertisers and all advertisers created in the future.

    • Choose Select specific items to which you want to grant access to only give Adverity permission to access the selected advertisers. Adverity will not automatically have access to advertisers created in the future. You will need to grant Adverity access to any advertisers created in the future.

As a result, Adverity has access to StackAdapt (GraphQL) using the credentials you provided.

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:

  1. (Optional) Rename your datastream.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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?

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_start and $dt_end variables as ISO8601Date or ISO8601DateTime. Adverity fills them with the start and end of the fetched date range.

  • To collect more than one page of results, declare the $cursor variable, pass it as the after argument, and request pageInfo with endCursor and hasNextPage.

  • For delivery and insight reports, request __typename on 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
        }
      }
    }
  }
}