Advertiser queries

After creating the advertiser, you can retrieve advertiser details using either the GraphQL or REST APIs. While the REST endpoints allow you to retrieve only one advertiser at a time, the GraphQL API enables you to create custom queries to search across multiple associated child records.

TIP: If you're new to GraphQL, explore our GraphQL API Resource Hub to learn the basics—like query anatomy, authentication, and rate limits—as well as how to run bulk queries.

The following sections provide examples of the advertiser query that you can use to look up advertiser information.

Look up campaign performance metrics by date range

With the GraphQL API, you can create and customize advertiser queries and include reporting fields that provide key performance metrics for tracking KPIs, cost and bidding, media quality, and the overall effectiveness of all campaigns associated with the advertiser. You can either retrieve lifetime data or organize it by day or hour to help analyze trends, optimize bids, and measure engagement effectively. Whether you're evaluating media efficiency or optimizing your bidding strategy, these detailed performance metrics can help you make informed, data-driven decisions.

TIP: You can also use the reporting field to retrieve performance metrics at the campaign and ad group level.

Here's what you need to know about looking up advertiser performance metrics by date range:

• These metrics also include data from all of the ad groups and campaigns associated with the advertiser.
• You can filter the metrics only by date.
• If you don't include a date range in the where filter, the query returns the lifetime metrics for all campaigns associated with the advertiser.
• You can retrieve metrics at the following time intervals, specified in the dimensions field:
  • Hourly (last 30 days)
  • Daily (last year)
• If you don’t include the dimensions field, the query returns aggregated totals for each metric without grouping data by time interval.

The following advertiser GraphQL query retrieves all metrics you can use to optimize campaign performance, manage spend and bidding, and so on. The date range is specified using gte (start, inclusive) and lt (end, exclusive) for the reporting period.

query GetAdvertiserPerformanceMetricsbyDateRangeExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    reporting {
      generalReporting(
        where: { date: { gte: "2025-02-01", lt: "2025-03-01" } }
      ) {
        nodes {
          dimensions {
            time {
              day
            }
          }
          metrics {
            adPlays
            bids
            clicks
            conversions
            cpa {
              advertiserCurrency
            }
            cpc {
              advertiserCurrency
            }
            cpcv {
              advertiserCurrency
            }
            cpm {
              advertiserCurrency
            }
            ctr
            customCpa {
              advertiserCurrency
            }
            customRoas {
              advertiserCurrency
            }
            impressions
            revenue
            roas {
              advertiserCurrency
            }
            spend {
              advertiserCurrency
            }
            tvQualityCpm {
              advertiserCurrency
            }
            tvQualityIndex
            vCpm {
              advertiserCurrency
            }
            videoCompletionRate
            viewability
            winRate
          }
        }
      }
    }
  }
}

Look up advertiser details

The following GraphQL query retrieves key metric details, such as channel and funnel location counts, for an advertiser by its ID.

query GetAdvertiserKeyMetricDataExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    id
    name
    isFavoriteForUser
    logo
    channelCount
    totalCampaignChannelCount
    funnelLocationCount
    totalFunnelLocationCount
  }
}

Look up advertiser seeds

The following GraphQL query retrieves seed details for an advertiser.

query GetAdvertiserSeedsExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    id
    name
    seeds {
      createdAt
      id
      isDefault
      lastUpdatedAt
      name
      targetingData {
        contextualInclusion {
          ids
          keyphrases
          urls
        }
        countryFilter {
          id
          name
        }
        firstPartyInclusion {
          name
        }
        targetingDataId
      }
    }
  }
}

Look up advertiser data segments

The following GraphQL query retrieves advertiser first-party data segments. It is the equivalent of the dmp/firstparty/advertiser REST endpoint.

TIP: When querying for as much first-party data as possible, to minimize query complexity, avoid requesting the totalCount field.

query GetFirstPartyDataExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    firstPartyData(
      first: 10
      where: {
        name: { contains: "SEGMENT_NAME_OR_OTHER_SEARCH_TERM_PLACEHOLDER" }
      }
    ) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        name
        id
        activeUniques {
          householdCount
          idsConnectedTvCount
          idsCount
          idsInAppCount
          idsWebCount
          personsCount
        }
      }
    }
  }
}

Multiple search terms can be combined in a single request. For example, to retrieve first-party data for multiple advertisers, use an array of advertiser IDs. The following is a code fragment example:

query GetFirstPartyDataForMultipleAdvertisersExample {
    advertisers(first: 50, where: { id: { in: ["ADVERTISER_ID_PLACEHOLDER_01", "ADVERTISER_ID_PLACEHOLDER_02", "ADVERTISER_ID_PLACEHOLDER_03"] } })

Look up advertiser settings

The following GraphQL query retrieves advertiser settings (also known as preferences in the UI), such as attribution windows, viewability, tracking, and so on.

query GetAdvertiserPreferencesExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    id
    name
    description
    domainAddress
    currency {
      id
      name
    }
    partner {
      id
      name
      chinaMSASigned
    }
    clickDedupeWindowInSeconds
    conversionDeDupeWindowInSeconds
    ignoreReferralUrlInConversion
    useMediaCostBasisForCampaignFees
    logo
    attribution {
      clickLookbackWindow
      clickInterval
      impressionInterval
      impressionLookbackWindow
    }
    defaultRightMediaOffer {
      id
      name
    }
    rightMediaOfferTypes {
      id
      name
    }
    availableIndustryCategories {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
    availableIndustrySubCategories {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
    industryCategory {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
    industrySubCategory {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
    brandOwner
    assignedBrands {
      id
      name
      owner
    }
    tracking {
      defaultUrls {
        selectedTrackingType
        partnerDefault
        advertiserDefault
        creativeTypes
      }
      defaultThirdPartyTags {
        selectedTrackingType
        partnerDefault
        advertiserDefault
        creativeTypes
      }
      defaultClickUrl {
        selectedTrackingType
        partnerDefault
        advertiserDefault
        creativeTypes
      }
    }
    viewability {
      availableProviders {
        displayName
        id
        isPartnerDefault
        fees {
          displayFee
          videoFee
        }
        settings {
          profileDisplayName
          providerId
          displaySamplingRate
          videoSamplingRate
        }
      }
      selectedProviderId
      settingsOverride {
        profileDisplayName
        providerId
        displaySamplingRate
        videoSamplingRate
      }
    }
    defaultPartnerViewabilitySettings {
      profileDisplayName
      providerId
      displaySamplingRate
      videoSamplingRate
    }
    political {
      categoryIds
      isBallotMeasure
      isCandidateElection
      candidateCount
    }
    isBlockedFromHhSolution
  }
}

Look-up live campaigns with highest CPM

The following GraphQL GetHighestCpmLiveCampaignsExample query retrieves a list of live campaigns that have the highest CPM. See also On-demand reporting queries.

query GetHighestCpmLiveCampaignsExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    campaigns(
      first: 25
      where: { status: { in: [LIVE, LIVE_NOT_SPENDING] } }
      order: [
        {
          campaignReporting: {
            metric: CPM_IN_ADVERTISER_CURRENCY
            direction: DESC
          }
        }
      ]
    ) {
      nodes {
        name
        reporting {
          generalReporting {
            nodes {
              metrics {
                cpm {
                  advertiserCurrency
                }
              }
            }
          }
        }
      }
    }
  }
}

Look up advertiser metadata

The following GraphQL query retrieves the programmatic tile metadata of an advertiser.

query GetAdvertiserTilesExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    id
    name
    programmaticTiles {
      isKoaOptimized
      isUserOptimized
      metadataSummaries
      type
    }
  }
}

Look up tracking tags

The following GQL query uses a trackingTags filter to find the names and IDs of tracking tags used by an advertiser. To learn more about using filters, see GraphQL API queries in our GraphQL Resource Hub.

query GetTrackingTagNamesExample {
  advertiser(id: "ADVERTISER_ID_PLACEHOLDER") {
    trackingTags(where: {name: {eq: "TRACKING_TAGS_OBJECT_NAME_PLACEHOLDER"}}) {
      nodes {
        name
        id
      }
    }
  }
}

Look up Prism settings

The following GraphQL query checks whether Prism is available and enabled for an advertiser.

query GetPrismStatusExample($advertiserId: ID!) {
  advertiser(id: $advertiserId) {
    dataSettings {
      prism {
        isAvailable
        isEnabled
        metadata
      }
    }
  }
}