Campaign Management Query API

Use the Campaign Management Query API to quickly retrieve detailed information and performance metrics from your campaigns, goals, and ads. These endpoints allow you to build your own interfaces to view the information in your account.

Considerations

Take the following considerations into account when using the Campaign Management Query REST API endpoints:
  • The Campaign Management Query endpoints give you quick access to the data collected for your campaigns, goals, and ads, with only an ingestion delay of one hour.
  • The Campaign Management Query endpoints provide totals for the requested metrics. If you need a breakdown of the metrics based on time, like for each month, then use the Custom Reporting API.
  • The Campaign Management Query endpoints provide the metrics described in the endpoints for the campaigns, goals, and ads. If you require other metrics, then use the Custom Reporting API.

Date and Time Format

All date and time fields must be ISO-8601 formatted date and time strings built up as follows:
  • start with YYYY-MM-DD, indicating year (YYYY), month (MM), and day (DD)
  • followed by a letter T
  • followed by hh:mm:ss, indicating hour (hh), minutes (mm), and seconds (ss). Indicating seconds is optional.
  • followed by Z to indicate the UTC time zone or ±hh:mm to indicate the offset from UTC in positive or negative direction (±) in hours (hh) and optionally minutes (mm)

The API always returns all date and time fields in UTC.

Response Body Format

The Campaign, Goal, and Ad Query endpoints described in the following pages, return response bodies with the complete or a part of the following format, depending on the endpoint you are accessing and query parameters you are using:

  • campaigns (object): an array of campaign objects, which is composed of the following information:
    • id (string): the ID of the campaign
    • name (string): the name of the campaign
    • description (string): the description of the campaign
    • customId (string): the custom ID of the campaign
    • start (string): ISO-8601 formatted date and time string indicating the earliest start date and time of the goals, if there are any goals linked to the campaign
    • end (string): ISO-8601 formatted date and time string indicating the latest end date and time of the goals, if there are any goals linked to the campaign and at least one of the goals has an end date
    • brand (object): the brand associated with the campaign:
      • id (string): the ID of the entity
    • agency (object): the agency associated with the campaign:
      • id (string): the ID of the entity
    • advertiser (object): the advertiser associated with the campaign:
      • id (string): the ID of the entity
    • state (string): the state of the campaign. Possible values are disabled, enabled, or archived
    • ignoreGlobalExternalTrackers (boolean): indicates whether the campaign is set to include the global trackers set up in the account or not
    • includedInForecast (boolean): indicates whether the campaign gets included in any forecasts or not
    • exclusive (boolean): indicates the campaign's mode; false means it is a normal campaign, true means it is an exclusive campaign
    • deleted(boolean): indicates whether or not the campaign was deleted
    • sequenceScope (string): indicates the scope of the goal sequence set in the campaign. Possible values are session and lifetime
    • priority (object): indicates the priority of the object and where the priority was set. The value is expressed as a number between 1 (highest) and 10 (lowest):
      • value (integer): indicates the object's value
      • origin(object): indicates whether the priority is inherited from another entity (site (global) > campaign > goal) or set directly on the object:
        • id (string): the ID of the object where the value comes from
        • href (string): a link to the object where the value comes from. Not available when entity equals site
        • entity (string): the entity where the value comes from
    • frontload (object): indicates how much of the object should be delivered as quickly as possible, and where the frontload was set. The value is expressed as a percentage between 0% (evenly over campaign period) and 100% (as fast as possible):
      • value (integer): indicates the object's value
      • origin(object): indicates whether the frontload is inherited from another entity (site (global) > campaign > goal) or set directly on the object:
        • id (string): the ID of the object where the value comes from
        • href (string): a link to the object where the value comes from. Not available when entity equals site
        • entity (string): the entity where the value comes from
    • metrics (object): indicates the metrics requested for the campaign and their values:
      • impression (integer): the amount of impressions delivered on the campaign
      • clickThrough (integer): the amount of times a click-through link was activated on the ads associated with the campaign
      • start (integer): the amount of times playback started for ads associated with the campaign, which is generally equal to the amount of impressions
      • firstQuartile (integer): the amount of times the ads associated with the campaign were viewed to at least 25% completion
      • midpoint (integer): the amount of times the ads associated with the campaign were viewed to at least 50% completion
      • thirdQuartile (integer): the amount of times the ads associated with the campaign were viewed to at least 75% completion
      • complete (integer): the amount of times the ads associated with the campaign were viewed to their completion
    • goals (object): an array of goal objects associated with the campaign, which is composed of the following information::
      • id (string): the ID of the goal
      • campaign (object): the associated campaign:
        • id (string): the ID of the entity
        • href (string): a link to the entity's details
      • name (string): the name of the goal
      • description (string): the description of the goal
      • target (object): the goal's target value, which together with the goal's type forms the complete target:
        • value (integer): the number of the target
        • unit (string): the unit of the value based on the goal type. Possible values are impression, percent, firstQuartile, midpoint, thirdQuartile, complete, and clickThrough
      • start (string): ISO-8601 formatted date and time string indicating the start date and time of the goal
      • end (string): ISO-8601 formatted date and time string indicating the end date and time of the goal
      • pricing (object): indicates the price of the goal according to the pricing model set on the goal:
        • value (number): the price of the goal
        • pricingModel (string): the pricing model of the goal. Possible values are: budget (fixed price), cpm (cost per thousand), cpmv25, cpmv50, cpmv75, cpmv100 (cost per thousand for 25%, 50%, 75%, or 100% ad completion), cpc (cost per click), noPricing
      • type (string): the type of goal. Possible values are shareOfVoice, impression, unlimitedImpression, rtb (priority unreserved), firstQuartile (25% Ad Completion), midpoint (50% Ad Completion), thirdQuartile (75% Ad Completion), complete (100% Ad Completion), clickThrough
      • deleted (boolean): indicates whether or not the goal was deleted
      • priority (object): indicates the priority of the object and where the priority was set. The value is expressed as a number between 1 (highest) and 10 (lowest):
        • value (integer): indicates the object's value
        • origin(object): indicates whether the priority is inherited from another entity (site (global) > campaign > goal) or set directly on the object:
          • id (string): the ID of the object where the value comes from
          • href (string): a link to the object where the value comes from. Not available when entity equals site
          • entity (string): the entity where the value comes from
      • customId (string): the custom ID of the goal
      • adPosition (string): the position where the ads associated with the goal are delivered. When an ad break has multiple positions, then this value affects where ads from this goal are placed in the ad break. Possible values are any, first, last, firstOrLast, and breakExclusive
      • goalSequence (object): indicates whether the goal is part of a sequence in a campaign:
        • sequence (integer): indicates the position of the goal in the sequence
          Note: Multiple goals in the campaign can have the same sequence number.
        • totalAmountOfGoals (integer): indicates the amount of goals in the campaign
        • sequenceScope (string): indicates the scope of the goal sequence set in the campaign. Possible values are session and lifetime
      • projectedDelivery (integer): indicates how much of the target is projected to be delivered. This field is only available for goals with an end date within 100 days from now and one of the following delivery goal types: impression, firstQuartile, midpoint, thirdQuartile, complete, and clickThrough
      • skipSettings (object): indicates the object's skip policy and where it originates from. Skip settings consist of:
        • value (object): indicates the skip policy that applies to the object:
          • showWhen (string): indicates whether or not skipping is allowed and when. Possible values are: always, afterFirstUnique, never
          • resetAfter (integer): indicates after how much time, expressed in hours, the view count resets in case showWhen equals afterFirstUnique, and the viewer needs to see the ad once before the skip button is shown next time an ad is served to the same viewer. Possible values are: 1, 2, 3, 6, 12, 24, 36, 48.
          • skipOffset (object): indicates after how much time the skip button should be shown on the ad. This field is only available if showWhen is present and equal to always or afterFirstUnique
            • value (integer): the amount of seconds or percentage after which the skip button should be shown on the ad
            • unit (string): indicates in which unit the skipOffset is expressed. Possible values are seconds or percent
          • parentOverride (boolean): true indicates that the current object overrides the skip policy somewhere in the hierarchy (campaign > goal > ad), false indicates there is no override. A reference to the object where the skip policy comes from is available in the origin object.
        • origin (object): indicates whether the skip policy is overriden in and inherited from another object in the hierarchy (campaign > goal > ad) or set directly on the current object:
          • id (string): the ID of the object where the value comes from
          • href (string): a link to the object where the value comes from. Not available when entity equals site
          • entity (string): the entity where the value comes from
      • cap (object): indicates whether the goal has a total impression cap or a daily impression cap, and the amount of the cap:
        • capType (string): indicates the type of cap, which is either totalCap (total impression cap which can be set on % Ad Completion, Click throughs, and Share of Voice (%) goals) or dailyCap (daily impression cap which can be set on Impression goals, if daily cap is enabled for the account)
        • capValue (integer): indicates the amount of the cap
      • frontload (object): indicates how much of the object should be delivered as quickly as possible, and where the frontload was set. The value is expressed as a percentage between 0% (evenly over campaign period) and 100% (as fast as possible):
        • value (integer): indicates the object's value
        • origin(object): indicates whether the frontload is inherited from another entity (site (global) > campaign > goal) or set directly on the object:
          • id (string): the ID of the object where the value comes from
          • href (string): a link to the object where the value comes from. Not available when entity equals site
          • entity (string): the entity where the value comes from
      • goalMode (string): indicates the goal mode. Possible values are normal or sponsor
      • metrics (object): indicates the metrics requested for the goal and their values:
        • impression (integer): the amount of impressions delivered on the goal
        • clickThrough (integer): the amount of times a click-through link was activated on the ads associated with the goal
        • start (integer): the amount of times playback started for ads associated with the goal, which is generally equal to the amount of impressions
        • firstQuartile (integer): the amount of times the ads associated with the goal were viewed to at least 25% completion
        • midpoint (integer): the amount of times the ads associated with the goal were viewed to at least 50% completion
        • thirdQuartile (integer): the amount of times the ads associated with the goal were viewed to at least 75% completion
        • complete (integer): the amount of times the ads associated with the goal were viewed to their completion
        • delivered (integer): the amount of the goal's type that was delivered for the goal
        • ctr (number): only available on goal objects, the number of click-throughs recorded for the goal divided by the number of impressions delivered on the goal, also known as the click-through rate
        • completionRate (number): only available on goal objects, the number of times the ads associated with the goal were viewed completely divided by the number of impressions delivered on the goal
        • ecpm (number): only available on goal objects, calculated effective cost per thousand impressions based on the configured pricing for the goal
      • ads (object, optional): an array of ad objects associated with the goal, which is composed of the following information:
        • id (string): the ID of the ad
        • name (string): the name of the ad
        • creative (object): the creative associated with the ad. Different fields are returned, depending on the creative type:
          • type (string): the type of creative. Possible values are: standard, standardThirdparty, standardPlaceholder (where you specify the type of insertion point, but you assign the creative later), pause, pausePlaceholder, iptv, iptvPlaceholder, overlay, overlayPlaceholder, companionBanner, companionBannerThirdparty, rtb, rtbPlaceholder, takeover, takeoverPlaceholder, takeoverThirdparty, pixeltracker, placeholder1 (where you do not specify the type of ad yet), placeholder1Placeholder (where you do not specify the type of ad or assign a creative yet), placeholder1Thirdparty (where you do not specify the type of 3rd party ad or assign a creative yet), unknown (only in case the creative does not fit into any of the other values)
          • insertionPoint (string): indicates when the creative should be shown. Possible values are preroll, midroll, postroll
          • vastUri (string): URI to the location of the 3rd party creative
          • vpaidStrict (boolean): indicates the allowed behaviour of 3rd party VPAID ads. true means only linear ads are allowed, false means non-linear ads are allowed as well
          • vpaidCountdown (boolean): indicates whether the standard Ooyala countdown text is visible on the 3rd party VPAID ad
          • estimatedAdDuration (integer): indicates the duration of the 3rd party or IPTV ad in seconds and is needed if you are using time based breaks
            Note: If the 3rd party or IPTV ad does not have an estimated duration, or exceeds the time based break duration, it will not get selected.
          • asset (object): the actual creative file that you need to associate with your ads
            • id (string): the ID of the asset
            • href (string): the URL to the location of the asset
          • videoCreativeId (string): only present for IPTV ads and indicates the ID of the video creative stored in the IPTV closed network
          • linkText (string): only present for overlay ads and indicates the clickable text that provides a link to the destination page
          • clickDestinationUri (string): the click-through URL of the creative
          • bannerArea (object): only present for companion banner ads and indicates a predefined area (zone) on your site to host the ad
            • id (string): the ID of the banner area the companion banner is assigned to
            • href (string): the URL to the location of the banner area the companion banner is assigned to
          • template (string): only present for companion banner ads and indicates the code injected into your website's zone to trigger the companion banner ad
          • marketplaceId (string): only present for RTB ads and indicates the ID of the marketplace the RTB ad is linked to
          • unknownType (string): in case the type of the creative is unknown, then this field holds whatever string was entered as the type of the creative
        • enabled (boolean): indicates whether the ad is enabled or not
        • campaign (object): the campaign the ad is associated with:
          • id (string): the ID of the entity
          • href (string): a link to the entity's details
        • goal (object): the goal the ad is associated with:
          • id (string): the ID of the entity
          • href (string): a link to the entity's details
        • description (string): the description of the ad
        • weight (object): the weight of the ad, which indicates in which portion of the cases a certain ad in a goal should be selected over another ad of the same format or insertion point in the same goal:
          • proportional (boolean): indicates if this ad's weight is proportionally split between ads of the same format or ads of the same insertion point (true), or if it is manually overridden (false)
          • totalOverridden (number): sum of all overridden weights for ads of the same format and insertion point
          • value (number): the weight of the ad, possible value is between 0.0 and 1
        • customId (string): the custom ID of the ad
        • start (object): the start date and time of the ad. Value is fetched from goal if not set on the ad:
          • value (string): an ISO-8601 formatted date and time string
          • origin (object): indicates whether the start date and time is inherited from the goal or set on the ad:
            • id (string): the ID of the object where the value comes from
            • href (string): a link to the object where the value comes from.
            • entity (string): the entity where the value comes from
        • end (object): the end date and time of the ad. Value is fetched from goal if not set on the ad:
          • value (string): an ISO-8601 formatted date and time string
          • origin (object): indicates whether the end date and time is inherited from the goal or set on the ad:
            • id (string): the ID of the object where the value comes from
            • href (string): a link to the object where the value comes from.
            • entity (string): the entity where the value comes from
        • externalTrackers (object): any external tracker set on the ad:
          • id (string): the ID of the external tracker
          • url (string): the URL of the external tracker
          • event (string): the event for which the external tracker should be triggered. Possible values are impression, clickThrough, start, firstQuartile, midpoint, thirdQuartile, complete, mute, unmute, pause, rewind, resume, fullscreen, expand, close
        • deviceContainers (object): list of device groups targeted by the ad:
          • id: the ID of the device group targeted by the ad
        • created (string): the creation date and time of the ad in ISO-8601 format
        • modified (string): the last date and time the ad was modified in ISO-8601 format
        • metrics (object): indicates the metrics requested for the ad and their values:
          • impression (integer): the amount of impressions delivered on the ad
          • clickThrough (integer): the amount of times a click-through link was activated on the ad
          • start (integer): the amount of times playback started on the ad, which is generally equal to the amount of impressions
          • firstQuartile (integer): the amount of times the ad was viewed to at least 25% completion
          • midpoint (integer): the amount of times the ad was viewed to at least 50% completion
          • thirdQuartile (integer): the amount of times the ad was viewed to at least 75% completion
          • complete (integer): the amount of times the ad was viewed to its completion
          • delivered (integer): the amount of the goal's type that was delivered for the ad
  • pagination (object): indicates the pagination information, total amount of objects, the amount of objects to show for each page, the page you are currently on, and links to first, next, previous, and/or last page:
    • totalCount (integer): the total amount of objects that the request yielded
    • pageSize (integer): the size of the page, which indicates the maximum number of objects the requests retrieves for one page
    • pageNumber (integer): the page you are currently on
    • links (object): links to first, next, previous, and/or last page, depending on the page you are currently on. Available if totalCount is greater than pageSize:
      • first (string): link to first page
      • next (string): link to next page
      • previous (string): link to previous page
      • last (string): link to last page
https://help.ooyala.com/sites/all/libraries/dita/en/video-advertising/oadtech/ad_serving/dg/rest_campaign_management_query_api.html

Was this article helpful?