Goal Performance Requests

Warning: All Performance REST APIs are currently on version 0, which means they have not been finalised yet and may still change significantly.

Use the Goal Performance API to request perfomance metrics from goals and optionally their associated ads.

Getting Started

  • Base URL: https://api.videoplaza.com/v0/goals.
  • Requests: GET requests are used. You pass parameters by using common REST parameters like PATH, QUERY, and MATRIX, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Swagger documentation: https://api.videoplaza.com/v1/swagger
  • Related user documentation:

Considerations

Take the following considerations into account when using to the Performance REST API endpoints:
  • The Performance endpoints give you quick access to the data collected for your campaigns, goals and ads, with only an ingestion delay of one hour.
  • The Performance 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 Performance 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.
Warning: All Performance REST APIs are currently on version 0, which means they have not been finalised yet and may still change significantly.

Date and Time Format

All date and time fields may only contain date 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.

Response Body Format

The endpoints described here, return response bodies with the complete or a part of the following format:

  • data (object): an array of goal objects, or one goal object, which is composed of the following information:
    • id (string): the ID of the goal
    • campaignId (string): the ID of the associated campaign
    • name (string, optional): the name of the goal
    • description (string, optional): the description of the goal
    • customId (string, optional): the custom ID of the goal, if it is set
    • 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, like the amount of impressions
      • unit (string): the unit of the value
    • start (string, optional): the start date and time of the goal
    • end (string, optional): the end date and time of the goal
    • pricing (object, optional): indicates how much the price is for the goal and according to which pricing model:
      • value (number): the price of the goal
      • pricingModel (string): the pricing model of the goal, the possible values are: BUDGET (fixed price), CPM (cost per million), CPMV_25 (cost per million for at least 25% ad completion), CPMV_50 (cost per million for at least 50% ad completion), CPMV_75 (cost per million for at least 75% ad completion), CPMV_100 (cost per million for completed ads), CPC (cost per million clicks), NO_PRICING
    • 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, first or last, break exclusive
    • type (string): the type of goal, the possible values are shareOfVoice, impression, unlimitedImpression
    • deleted (Boolean, optional): whether or not the goal was deleted
    • goalSequence (object, optional): indicates that the goal is part of a sequence in a campaign
      • sequenceScope (string): indicates the scope of the sequence set in the campaign. Possible values are session and lifetime.
      • 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
    • cap (object, optional): indicates whether the goal has an impression or daily cap, and the amount of the cap
      • capType (string): indicates the type of cap, which is either totalcap (which can be set on % Ad Completion, Click throughs, Sponsor and Share of Voice (%) goals) or dailycap (which can be set on Impression goals, if daily cap is enabled for the account).
      • capValue (integer): indicates the amount of the cap
    • skipSettings (object): indicates the object's skip policy, which is applied to any ads related to the object, and where the policy originates from. Skip settings consist of:
      • value (object): indicates the skip policy that applies to the object:
        • skipAdPolicyStrategy (string, optional): indicates whether or not skipping is allowed and when. Possible values are: always, afterFirstImpression, never
        • skipAdPolicySkipOffset (integer, optional): indicates after how much time the skip button should be shown on the ad. This field is only available if skipAdPolicyStrategy is present and equal to always or afterFirstImpression
        • skipAdPolicySkipOffsetTimeUnit (string, optional): indicates in which unit the skipAdPolicySkipOffset is expressed. Possible values are second or percent
        • skipAdPolicyResetInterval (integer, optional): indicates after how much time, expressed in hours, the view count resets in case skipAdPolicyStrategy equals afterFirstImpression, and the viewer needs to see the ad once before a skip button is shown on the next time the ad is served the same viewer
        • skipAdPolicyOverride (Boolean): indicates if skip policy is overriden somewhere in the hierarchy (campaign > goal > ad) of the current object (true), or if the policy is inherited from the applicable insertion policy at the time of the request to Pulse (false). If the value is true, a reference to the object where the policy is overriden is available in the origin object or the self object
      • origin (object, optional): indicates that the skip policy is overriden in and inherited from another object in the hierarchy (campaign > goal > ad) of the current object:
        • id: the ID of the object where the inheritance comes from
        • href: a link to the object where the inheritance comes from
      • self (object, optional): indicates that the skip policy is overriden in the current object:
        • id: the ID of the object where the inheritance comes from
        • href: a link to the object where the inheritance comes from
    • 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, optional): indicates the objects value set directly on the object
      • resolvedValue (integer): indicates the objects inherited value. In case the value was set directly, then both value and resolvedValue are present and are always the same.
    • customId (string, optional): the custom ID of the goal, if it is set
    • frontLoad (object): indicates how much of the object should be delivered as quickly as possible, and where the value was set. The value is expressed in percentage:
      • value (integer, optional): indicates the objects value set directly on the object
      • resolvedValue (integer): indicates the objects inherited value. In case the value was set directly, then both value and resolvedValue are present and are always the same.
    • projectedDelivery (integer, optional): 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:
      • Impressions
      • xx% Ad Completion (25%, 50%, 75%, and 100%)
      • Click throughs
    • metrics (object, optional): indicates the requested metrics and their values:
      • impression (integer, optional): the number of impressions delivered on the object
      • error (integer, optional): the number of errors recorded on the object
      • click_through (integer, optional): the number of click-throughs recorded on the associated ad(s) for the object
      • ad_started (integer, optional): the number of times playback started for associated ads of the object. In general this is equal to the amount of impressions
      • ad_25_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 25%
      • ad_50_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 50%
      • ad_75_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 75%
      • ad_completed (integer, optional): the number of times the associated ads for the object were viewed completely
      • ctr (number, optional): the number of click-throughs recorded for an object divided by the number of impressions delivered on that object, also known as the click-through rate
      • completion_rate (number, optional): the number of times the associated ads for the object were viewed completely divided by the number of impressions delivered on that object
      • delivered (integer, optional): only available on goal objects, and only when requesting all metrics (metrics=all). It indicates the amount of the goal's type that was delivered
    • ads (object, optional): the collection of ads associated with the goal:
      • id (string): the ID of the ad
      • name (string): the name of the ad
      • creative (object): the creative associated with the ad
        • type (string): the type of creative, the possible values are: standard, thirdparty, placeholder (only in case no creative was assigned yet), spotPlaceholder, pause, pausePlaceholder, unknown (only in case the creative does not fit into any of the other values)
        • insertionPoint (string, optional): indicates when the creative should be shown, the possible values are preroll, midroll, postroll
        • vastUri (string, optional): URI to the location of the third party creative
        • vpaidStrict (Boolean, optional): indicates the allowed behaviour of VPAID ads. true means only linear ads are allowed, false means non-linear ads are allowed as well
        • vpaidCountdown (Boolean, optional): indicates whether the standard Ooyala countdown text is visible on the third party VPAID ad
        • assetId (string, optional): the ID of the creative
        • clickDestinationUri (string, optional): the click-through URL of the creative
        • unknownType (string, optional): 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
      • campaignId (string): the ID of the campaign the ad is associated with
      • goalId (string): the ID of the goal the ad is associated with
      • zone (string, optional): only present for companion banner ads and indicates the ID of the zone the companion is assigned to
      • description (string, optional): the description of the ad
      • weight (number, optional): 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 in the same goal. The value is between 0.0001 and 1
      • customId (string, optional): the custom ID of the ad, if set
      • start (string, optional): the start date and time of the ad
      • end (string, optional): the end date and time of the ad
      • externalTrackers (object): any external tracker set on the ad
        • id (string, optional): the ID of the external tracker
        • url (string, optional): the URL of the external tracker
        • event (string, optional): the event for which the external tracker should be triggered
      • deviceContainers (string array): the device groups targeted by the ad
      • created (string): the creation date and time of the ad
      • modified (string): the last date and time the ad was modified
      • metrics (object, optional): indicates the requested metrics and their values:
        • impression (integer, optional): the number of impressions delivered on the object
        • error (integer, optional): the number of errors recorded on the object
        • click_through (integer, optional): the number of click-throughs recorded on the associated ad(s) for the object
        • ad_started (integer, optional): the number of times playback started for associated ads of the object. In general this is equal to the amount of impressions
        • ad_25_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 25%
        • ad_50_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 50%
        • ad_75_percent_completed (integer, optional): the number of times the associated ads for the object were viewed for at least 75%
        • ad_completed (integer, optional): the number of times the associated ads for the object were viewed completely
        • ctr (number, optional): the number of click-throughs recorded for an object divided by the number of impressions delivered on that object, also known as the click-through rate
        • completion_rate (number, optional): the number of times the associated ads for the object were viewed completely divided by the number of impressions delivered on that object
        • delivered (integer, optional): only available on goal objects, and only when requesting all metrics (metrics=all). It indicates the amount of the goal's type that was delivered
    • campaigns (object, optional): the collection of campaigns associated with the goals on the page:
      • "id_of_the_campaign" (object): this label is the ID of the campaign
        • id (string): the ID of the campaign
        • name (string): the name of the campaign
        • description (string, optional): the description of the campaign
        • customId (string, optional): the custom ID of the campaign, if it is set
        • start (string, optional): the earliest start date and time of the goals, if there are any goals linked to the campaign
        • end (string, optional): 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
        • brandId (string, optional): the ID of the brand associated with the campaign
        • agencyId (string, optional): the ID of the agency associated with the campaign
        • advertiserId (string, optional): the ID of the advertiser associated with the campaign
        • state (string, optional): the state of the campaign. Possible values are: DISABLED, ENABLED, ARCHIVED, or DELETED
        • ignoreGlobalExternalTrackers (Boolean, optional): whether the campaign is set to include the global trackers set up in the account or not
        • includedInForecast (Boolean, optional): whether the campaign gets included in any forecasts or not
        • exclusive (Boolean, optional): indicates the campaign's mode, which can be normal (false) or exclusive (true)
        • siteId (string): the ID of the account
        • 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, optional): indicates the objects value set directly on the object
          • resolvedValue (integer): indicates the objects inherited value. In case the value was set directly, then both value and resolvedValue are present and are always the same.
        • frontLoad (object): indicates how much of the object should be delivered as quickly as possible, and where the value was set. The value is expressed in percentage:
          • value (integer, optional): indicates the objects value set directly on the object
          • resolvedValue (integer): indicates the objects inherited value. In case the value was set directly, then both value and resolvedValue are present and are always the same.
  • pagination (object): indicates the pagination information, total amount of objects, the amount of objects to show for each page, and the page you are currently on:
    • totalCount (integer, optional): the total amount of data objects that the request yielded
    • pageSize (integer, optional): the size of the page, which indicates the maximum number of data objects the requests retrieves for one page
    • pageNumber (integere, optional): the page you are currently on

Get Performance Metrics for Multiple Goals

Method GET
URL /v0/goals
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params
Note: All query parameters are optional.
  • campaigns: add the parameter to the query string to list all campaigns associated to the goals returned in the request. By default, they are not listed.
  • metrics: enter a metrics=<value> for each metric you want listed in the results in the query string. Possible values are:
    • impression
    • click_through
    • ad_started
    • ad_25_percent_completed
    • ad_50_percent_completed
    • ad_75_percent_completed
    • ad_completed
    • all
  • goals.started.before: filter on goals which started before a specific date and time in the results. See Date and Time Format on how to format this field.
  • goals.started.after: filter on goals which started after a specific date and time in the results. See Date and Time Format on how to format this field.
  • goals.ended.before: filter on goals which ended before a specific date and time in the results. See Date and Time Format on how to format this field.
  • goals.ended.after: filter on goals which ended after a specific date and time in the results. See Date and Time Format on how to format this field.
  • goal.name: filter on goals which contain the given string (case sensitive) in their name. For example, if you enter 'goal' as the filter string, then the results would contain goals with names like 'somethinggoalsomething', but not names like 'somethingGoalsomething'.
  • campaign.name: filter on goals in campaigns which contain the given string (case sensitive) in their name. For example, if you enter 'campaign' as the filter string, then the results would contain goals from campaigns with names like 'somethingcampaignsomething', but not names like 'somethingCampaignsomething'.
  • goal.state: filter on goals in a specific state. Enter a goal.state=<value> for each state you want to filter on. Possible values are:
    • enabled
    • disabled
  • campaign.state: filter on goals in campaigns in a specific state. Enter a campaign.state=<value> for each state you want to filter on. Possible values are:
    • enabled
    • disabled
    • archived
  • ads: add the parameter to the query string to list the ads associated with the listed goals.
  • sorting; sort the resulting goals according to:
    • priority: their priority.
    • type: their delivery goal type.
    • booked: their booked amount of the delivery goal type.
    • start: their start date.
    • end: their end date.
    • goal_name: their name. This is the default.
    • campaign_name: the name of their associated campaign.
  • projections: set to true to return the projected delivery for the goal at the time of the request.
  • pageSize: enter the number of goals to return for each page. You can use this feature if you want to create pagination in your user interface. The value must be between 1 and 100. The default value is 10.
  • pageNumber: enter the number of the page you want the results from. This parameter works in combination with the pageSize parameter. The default value is 1. Based on the pageSize value you provide and the totalCount value returned (see Response Body Format), you can calculate how many pages there are in total.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see Response Body Format

Example:

Request header:

GET /v0/goals?campaigns&ads&metrics=all HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
  "data": [
    {
      "id": "2751a888-e075-41e2-8374-7347230bf800",
      "campaignId": "176ee697-4fdc-4148-b48f-0ac1276fee11",
      "name": "",
      "target": {
        "value": 75,
        "unit": "percent"
      },
      "start": "2017-09-06T11:43:08Z",
      "ads": [
        {
          "id": "80b6047d-93fa-4ae9-bb21-4861bb9dc7b0",
          "name": "Upload",
          "creative": {
            "type": "standard",
            "insertionPoint": "preroll",
            "assetId": "50f0fd4d-7754-49bb-8e6d-e7b189429982"
          },
          "enabled": false,
          "campaignId": "176ee697-4fdc-4148-b48f-0ac1276fee11",
          "goalId": "2751a888-e075-41e2-8374-7347230bf800",
          "metrics": {
            "impression": 0,
            "click_through": 0,
            "ad_started": 0,
            "ad_25_percent_completed": 0,
            "ad_50_percent_completed": 0,
            "ad_75_percent_completed": 0,
            "ad_completed": 0
          },
          "description": "",
          "externalTrackers": [],
          "deviceContainers": [
            "5faffabd-fd8f-47f8-9360-49a98b399ea1",
            "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
          ],
          "created": "2017-11-07T10:37:28Z",
          "modified": "2017-11-07T10:47:03Z"
        }
      ],
      "type": "shareOfVoice",
      "deleted": false,
      "priority": {
        "value": 10,
        "resolvedValue": 10
      },
      "metrics": {
        "impression": 0,
        "click_through": 0,
        "ad_started": 0,
        "ad_25_percent_completed": 0,
        "ad_50_percent_completed": 0,
        "ad_75_percent_completed": 0,
        "ad_completed": 0,
        "delivered": 0
      },
      "variant": "normal"
    }
  ],
  "campaigns": {
    "176ee697-4fdc-4148-b48f-0ac1276fee11": {
      "id": "176ee697-4fdc-4148-b48f-0ac1276fee11",
      "name": "campaign_name",
      "start": "2017-09-06T11:43:08Z",
      "advertiserId": "fd877e9d-e9c0-4e36-8c37-f6ab05506c21",
      "state": "ENABLED",
      "ignoreGlobalExternalTrackers": false,
      "includedInForecast": true,
      "exclusive": false,
      "siteId": "aaaa1111-bb22-cc33-dd44-eeeeee555555",
      "goals": [],
      "priority": {
        "value": 1,
        "resolvedValue": 1
      }
    }
  },
  "pagination": {
    "totalCount": 1,
    "pageSize": 10,
    "pageNumber": 1
  }
}

Get Performance Metrics for One Goal

Method GET
URL /v0/goals/{goalId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params goalId: the ID of the goal
Query params
  • ads: add the parameter to the query string to list the ads associated with the listed goals.
  • metrics: enter a metrics=<value> for each metric you want listed in the results in the query string. Possible values are:
    • impression
    • click_through
    • ad_started
    • ad_25_percent_completed
    • ad_50_percent_completed
    • ad_75_percent_completed
    • ad_completed
    • all
  • projections: set to true to return the projected delivery for the goal at the time of the request.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see Response Body Format. The response only contains one campaign object, without the data and pagination elements.

Example:

Request header:

GET /v0/goals/b22e12f0-4666-40c4-867e-a7955750da1e?ads&metrics=all HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
  "id": "2751a888-e075-41e2-8374-7347230bf800",
  "campaignId": "176ee697-4fdc-4148-b48f-0ac1276fee11",
  "name": "",
  "target": {
    "value": 75,
    "unit": "percent"
  },
  "start": "2017-09-06T11:43:08Z",
  "ads": [
    {
      "id": "80b6047d-93fa-4ae9-bb21-4861bb9dc7b0",
      "name": "Upload",
      "creative": {
        "type": "standard",
        "insertionPoint": "preroll",
        "assetId": "50f0fd4d-7754-49bb-8e6d-e7b189429982"
      },
      "enabled": false,
      "campaignId": "176ee697-4fdc-4148-b48f-0ac1276fee11",
      "goalId": "2751a888-e075-41e2-8374-7347230bf800",
      "metrics": {
        "impression": 0,
        "click_through": 0,
        "ad_started": 0,
        "ad_25_percent_completed": 0,
        "ad_50_percent_completed": 0,
        "ad_75_percent_completed": 0,
        "ad_completed": 0
      },
      "description": "",
      "externalTrackers": [],
      "deviceContainers": [
        "5faffabd-fd8f-47f8-9360-49a98b399ea1",
        "6b6535fb-7ca3-4aea-a783-92f99e698d4c"
      ],
      "created": "2017-11-07T10:37:28Z",
      "modified": "2017-11-07T10:47:03Z"
    }
  ],
  "type": "shareOfVoice",
  "deleted": false,
  "priority": {
    "value": 10,
    "resolvedValue": 10
  },
  "metrics": {
    "impression": 0,
    "click_through": 0,
    "ad_started": 0,
    "ad_25_percent_completed": 0,
    "ad_50_percent_completed": 0,
    "ad_75_percent_completed": 0,
    "ad_completed": 0,
    "delivered": 0
  },
  "variant": "normal"
}

Was this article helpful?