Goal Query Requests

Use the Goal Query API to retrieve detailed information and perfomance metrics from goals and optionally their associated ads.

Getting Started

  • Base URL: https://api.videoplaza.com/v3/goals.
  • Requests: GET requests are used. You pass parameters by using common REST parameters like PATH and QUERY, 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: Campaign API v3 - Goals
  • Related user documentation:
The Goal Query endpoints allows you to:

Query for Multiple Goals

This endpoint enables you to list all goals associated with your account. Various query parameters allow you to get very detailed and specific information on a subset of goals that match your query, all within one API call. You can expand ads associated with the goals, which results in a nested structure representing the hierarchy between goals and ads. You can also embed projections, which gives you information on the projected delivery for the goals at the time of the request, as well as metrics, to quickly retrieve one, several, or all available metrics for the listed goals. Embedded metrics are only returned on the goals and not on expanded ads, to allow scaling for larger accounts with many ads within goals. Paging is added by default but can also be specified using paging parameters, to further narrow down the result. This is especially important for heavy requests that include lots of embedded objects. The available query parameters are described in detail in the table below.

Method GET
URL /v3/goals
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params
Note: All query parameters are optional.
  • expand: enter expand=ads to the query string to expand all the ads associated with the listed goals.
    If the parameter is not present, a link to each ad's details is returned.
    "ads": [
                    {
                        "id": "<ad ID>",
                        "href": "https://api.videoplaza.com/v3/ads/<ad ID>"
                    }
                ]
  • embed: add the parameter to the query string to retrieve the metrics available for the goals and/or the projected delivery for goals at the time of the request. When listing all goals, the metrics are returned only for goals, never for expanded ads, if there are any. Possible values are metrics and projections.
    • Add embed=metrics to the query string to retrieve all the available metrics.
    • Add embed=metrics&metrics=<value> to the query string to retrieve one or several specific metrics. Possible values are:
      • impression
      • clickThrough
      • start
      • firstQuartile
      • midpoint
      • thirdQuartile
      • complete
      • delivered
      • ctr
      • completionRate
      • ecpm

      For example: embed=metrics&metrics=impression&metrics=clickThrough&metrics=complete

    • Add embed=projections to the query string to retrieve the projected delivery for the goal at the time of the request. Projected delivery is only available for goals.
  • goals.started.before: filter on goals that started before a specific date and time. See Date and Time Format on how to format this field.
  • goals.started.after: filter on goals that started after a specific date and time. See Date and Time Format on how to format this field.
  • goals.ended.before: filter on goals that ended before a specific date and time. See Date and Time Format on how to format this field.
  • goals.ended.after: filter on goals that ended after a specific date and time. See Date and Time Format on how to format this field.
  • goal.name: filter on goals which contain the given string (case-insensitive) anywhere in their name.
  • campaign.name: filter on goals in campaigns which contain the given string (case-insensitive) anywhere in their name.
  • campaign.id: filter on goals associated with a specific campaign based on that campaign's ID. You can only filter on a single campaign.
  • campaign.state: filter on goals associated with campaigns in a specific state. Enter a campaign.state=<value> for each state you want to filter on. Possible values are:
    • enabled
    • disabled
    • archived
  • 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.
  • sorting: sort the resulting goals according to one of the following:
    • 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.
    • goalName: their name. This is the default.
    • campaignName: the name of their associated campaign.
  • sortingOrder: specifies the sorting order, possible values are ascending (default) or descending.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see goals in the Response Body Format.

Example - No Expanded Objects:

Request header:

GET /v3/goals?goals.started.after=2018-07-19T00:00:00Z&embed=projections&embed=metrics HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "goals": [
        {
            "id": "4866d0b3-2686-4fed-a87a-8f419cf5c935",
            "campaign": {
                "id": "b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3",
                "href": "https://api.videoplaza.com/v3/campaigns/b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3"
            },
            "name": "Ooyala autumn goal",
            "description": "Sponsor goal",
            "target": {
                "value": 100,
                "unit": "percent"
            },
            "start": "2018-08-30T22:00:00Z",
            "end": "2018-10-31T23:00:00Z",
            "pricing": {
                "value": 8,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "a8ba0677-4e9e-4d65-a7ed-e5be2ef2a289",
                    "href": "https://api.videoplaza.com/v3/ads/a8ba0677-4e9e-4d65-a7ed-e5be2ef2a289"
                }
            ],
            "type": "shareOfVoice",
            "deleted": false,
            "priority": {
                "value": 5,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 8
            },
            "adPosition": "any",
            "sponsorPlacement": "default",
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "parentOverride": false
                }
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "sponsor"
        },
        {
            "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "name": "Ooyala summer goal I/II",
            "description": "Ooyala summer goal I/II",
            "target": {
                "value": 250000,
                "unit": "impression"
            },
            "start": "2018-07-19T22:00:00Z",
            "end": "2018-08-27T22:00:00Z",
            "pricing": {
                "value": 10,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "b15b100d-6c2b-4daf-94c4-7a53ea0da0f7",
                    "href": "https://api.videoplaza.com/v3/ads/b15b100d-6c2b-4daf-94c4-7a53ea0da0f7"
                }
            ],
            "type": "impression",
            "deleted": false,
            "priority": {
                "value": 4,
                "origin": {
                    "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                    "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
                    "entity": "campaign"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 10
            },
            "customId": "Custom goal ID",
            "adPosition": "any",
            "goalSequence": {
                "sequence": 1,
                "totalAmountOfGoals": 2,
                "sequenceScope": "lifetime"
            },
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "showWhen": "afterFirstUnique",
                    "resetAfter": 12,
                    "skipOffset": {
                        "value": 5,
                        "unit": "seconds"
                    },
                    "parentOverride": true
                },
                "origin": {
                    "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
                    "href": "https://api.videoplaza.com/v3/goals/e26d57f8-ba36-422e-8730-8b7e44311d9f",
                    "entity": "goal"
                }
            },
            "cap": {
                "capType": "dailyCap",
                "capValue": 11000
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "normal"
        },
        {
            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "name": "Ooyala summer goal II/II",
            "description": "Ooyala summer goal II/II",
            "target": {
                "value": 250000,
                "unit": "impression"
            },
            "start": "2018-08-15T22:00:00Z",
            "end": "2018-09-15T22:00:00Z",
            "pricing": {
                "value": 10,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "e9fc0519-b807-42fe-a101-bd7c65eea957",
                    "href": "https://api.videoplaza.com/v3/ads/e9fc0519-b807-42fe-a101-bd7c65eea957"
                }
            ],
            "type": "impression",
            "deleted": false,
            "priority": {
                "value": 4,
                "origin": {
                    "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                    "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
                    "entity": "campaign"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 10
            },
            "customId": "Custom goal ID",
            "adPosition": "any",
            "goalSequence": {
                "sequence": 2,
                "totalAmountOfGoals": 2,
                "sequenceScope": "lifetime"
            },
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "showWhen": "afterFirstUnique",
                    "resetAfter": 12,
                    "skipOffset": {
                        "value": 5,
                        "unit": "seconds"
                    },
                    "parentOverride": true
                },
                "origin": {
                    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "entity": "goal"
                }
            },
            "cap": {
                "capType": "dailyCap",
                "capValue": 11000
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "normal"
        }
    ],
    "pagination": {
        "totalCount": 3,
        "pageSize": 10,
        "pageNumber": 1
    }
}

Example - Expanded Objects:

Request header:

GET /v3/goals?goals.started.after=2018-07-19T00:00:00Z&expand=ads&embed=projections&embed=metrics HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "goals": [
        {
            "id": "4866d0b3-2686-4fed-a87a-8f419cf5c935",
            "campaign": {
                "id": "b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3",
                "href": "https://api.videoplaza.com/v3/campaigns/b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3"
            },
            "name": "Ooyala autumn goal",
            "description": "Sponsor goal",
            "target": {
                "value": 100,
                "unit": "percent"
            },
            "start": "2018-08-30T22:00:00Z",
            "end": "2018-10-31T23:00:00Z",
            "pricing": {
                "value": 8,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "a8ba0677-4e9e-4d65-a7ed-e5be2ef2a289",
                    "name": "Sponsor ad",
                    "creative": {
                        "insertionPoint": "preroll",
                        "type": "standardPlaceholder"
                    },
                    "enabled": true,
                    "description": "Sponsor ad",
                    "weight": {
                        "proportional": true,
                        "totalOverridden": 0,
                        "value": 1
                    },
                    "start": {
                        "value": "2018-08-30T22:00:00Z",
                        "origin": {
                            "id": "4866d0b3-2686-4fed-a87a-8f419cf5c935",
                            "href": "https://api.videoplaza.com/v3/goals/4866d0b3-2686-4fed-a87a-8f419cf5c935",
                            "entity": "goal"
                        }
                    },
                    "end": {
                        "value": "2018-10-31T23:00:00Z",
                        "origin": {
                            "id": "4866d0b3-2686-4fed-a87a-8f419cf5c935",
                            "href": "https://api.videoplaza.com/v3/goals/4866d0b3-2686-4fed-a87a-8f419cf5c935",
                            "entity": "goal"
                        }
                    },
                    "externalTrackers": [
                        {
                            "id": "7d78e034-95da-4773-a109-edae9f4cce60",
                            "url": "http://tracking.com",
                            "event": "impression"
                        }
                    ],
                    "deviceContainers": [
                        {
                            "id": "6b79564c-8a8c-102f-9f01-001e4f3cd645"
                        }
                    ],
                    "created": "2018-07-20T08:41:51Z",
                    "modified": "2018-07-20T08:41:51Z"
                }
            ],
            "type": "shareOfVoice",
            "deleted": false,
            "priority": {
                "value": 5,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 8
            },
            "adPosition": "any",
            "sponsorPlacement": "default",
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "parentOverride": false
                }
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "sponsor"
        },
        {
            "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "name": "Ooyala summer goal I/II",
            "description": "Ooyala summer goal I/II",
            "target": {
                "value": 250000,
                "unit": "impression"
            },
            "start": "2018-07-19T22:00:00Z",
            "end": "2018-08-27T22:00:00Z",
            "pricing": {
                "value": 10,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "b15b100d-6c2b-4daf-94c4-7a53ea0da0f7",
                    "name": "Ooyala pre-roll ad",
                    "creative": {
                        "insertionPoint": "preroll",
                        "asset": {
                            "id": "1a55837f-ed05-4abe-bbfd-3ac098e9bf7d",
                            "href": "https://api.videoplaza.com/v1/assets/1a55837f-ed05-4abe-bbfd-3ac098e9bf7d"
                        },
                        "clickDestinationUri": "http://ooyala.com",
                        "type": "standard"
                    },
                    "enabled": true,
                    "description": "Ooyala pre-roll ad",
                    "weight": {
                        "proportional": true,
                        "totalOverridden": 0,
                        "value": 1
                    },
                    "customId": "Custom ad ID",
                    "start": {
                        "value": "2018-07-19T22:00:00Z",
                        "origin": {
                            "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
                            "href": "https://api.videoplaza.com/v3/goals/e26d57f8-ba36-422e-8730-8b7e44311d9f",
                            "entity": "goal"
                        }
                    },
                    "end": {
                        "value": "2018-08-27T22:00:00Z",
                        "origin": {
                            "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
                            "href": "https://api.videoplaza.com/v3/goals/e26d57f8-ba36-422e-8730-8b7e44311d9f",
                            "entity": "goal"
                        }
                    },
                    "externalTrackers": [
                        {
                            "id": "2a632119-56cf-48dc-bbf8-222c19efc862",
                            "url": "http://click-tracking.com",
                            "event": "clickThrough"
                        },
                        {
                            "id": "51003782-c591-4ebe-9eb5-fad45e862345",
                            "url": "http://tracking.com",
                            "event": "impression"
                        }
                    ],
                    "deviceContainers": [
                        {
                            "id": "27375d12-e3ad-46ce-ad78-eece92928c90"
                        },
                        {
                            "id": "a6b5b571-c517-4597-861b-24d2d190d642"
                        }
                    ],
                    "created": "2018-07-20T08:29:49Z",
                    "modified": "2018-07-23T15:00:51Z"
                }
            ],
            "type": "impression",
            "deleted": false,
            "priority": {
                "value": 4,
                "origin": {
                    "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                    "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
                    "entity": "campaign"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 10
            },
            "customId": "Custom goal ID",
            "adPosition": "any",
            "goalSequence": {
                "sequence": 1,
                "totalAmountOfGoals": 2,
                "sequenceScope": "lifetime"
            },
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "showWhen": "afterFirstUnique",
                    "resetAfter": 12,
                    "skipOffset": {
                        "value": 5,
                        "unit": "seconds"
                    },
                    "parentOverride": true
                },
                "origin": {
                    "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
                    "href": "https://api.videoplaza.com/v3/goals/e26d57f8-ba36-422e-8730-8b7e44311d9f",
                    "entity": "goal"
                }
            },
            "cap": {
                "capType": "dailyCap",
                "capValue": 11000
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "normal"
        },
        {
            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "name": "Ooyala summer goal II/II",
            "description": "Ooyala summer goal II/II",
            "target": {
                "value": 250000,
                "unit": "impression"
            },
            "start": "2018-08-15T22:00:00Z",
            "end": "2018-09-15T22:00:00Z",
            "pricing": {
                "value": 10,
                "pricingModel": "cpm"
            },
            "ads": [
                {
                    "id": "e9fc0519-b807-42fe-a101-bd7c65eea957",
                    "name": "Ooyala mid-roll ad",
                    "creative": {
                        "insertionPoint": "midroll",
                        "asset": {
                            "id": "f24ce53c-f714-4820-9dbf-aa1bc578facb",
                            "href": "https://api.videoplaza.com/v1/assets/f24ce53c-f714-4820-9dbf-aa1bc578facb"
                        },
                        "clickDestinationUri": "http://ooyala.com",
                        "type": "standard"
                    },
                    "enabled": true,
                    "description": "Ooyala mid-roll ad",
                    "weight": {
                        "proportional": true,
                        "totalOverridden": 0,
                        "value": 1
                    },
                    "customId": "Custom ad ID",
                    "start": {
                        "value": "2018-08-15T22:00:00Z",
                        "origin": {
                            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                            "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                            "entity": "goal"
                        }
                    },
                    "end": {
                        "value": "2018-09-15T22:00:00Z",
                        "origin": {
                            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                            "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                            "entity": "goal"
                        }
                    },
                    "externalTrackers": [
                        {
                            "id": "7c0411b9-ef75-4c09-8ccc-e1108e2b3152",
                            "url": "http://start-tracking.com",
                            "event": "start"
                        },
                        {
                            "id": "a6c6f4d4-55c3-4107-aa32-0029b9c3af50",
                            "url": "http://pause-tracking.com",
                            "event": "pause"
                        }
                    ],
                    "deviceContainers": [
                        {
                            "id": "145299c6-ba02-45de-9995-c2dfaba44c8c"
                        },
                        {
                            "id": "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                        }
                    ],
                    "created": "2018-07-20T08:36:05Z",
                    "modified": "2018-07-20T08:36:05Z"
                }
            ],
            "type": "impression",
            "deleted": false,
            "priority": {
                "value": 4,
                "origin": {
                    "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                    "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
                    "entity": "campaign"
                }
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0,
                "ctr": 0,
                "completionRate": 0,
                "ecpm": 10
            },
            "customId": "Custom goal ID",
            "adPosition": "any",
            "goalSequence": {
                "sequence": 2,
                "totalAmountOfGoals": 2,
                "sequenceScope": "lifetime"
            },
            "projectedDelivery": 0,
            "skipSettings": {
                "value": {
                    "showWhen": "afterFirstUnique",
                    "resetAfter": 12,
                    "skipOffset": {
                        "value": 5,
                        "unit": "seconds"
                    },
                    "parentOverride": true
                },
                "origin": {
                    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "entity": "goal"
                }
            },
            "cap": {
                "capType": "dailyCap",
                "capValue": 11000
            },
            "frontload": {
                "value": 30,
                "origin": {
                    "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
                    "entity": "site"
                }
            },
            "goalMode": "normal"
        }
    ],
    "pagination": {
        "totalCount": 3,
        "pageSize": 10,
        "pageNumber": 1
    }
}

Query for One Goal

This endpoint enables you to get one goal associated with your account. You can expand ads associated with the goal, which results in a nested structure representing the hierarchy between goals and ads. You can also embed metrics and this way quickly retrieve one, several, or all available metrics for a goal and its ads, if expanded. The available query parameters are described in detail in the table below.

Method GET
URL /v3/goals/{goalId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params goalId: the ID of the goal
Query params
  • expand: enter expand=ads to the query string to expand all the ads associated with the goal.
    If the parameter is not present, a link to each ad's details is returned.
    "ads": [
                    {
                        "id": "<ad ID>",
                        "href": "https://api.videoplaza.com/v3/ads/<ad ID>"
                    }
                ]
  • embed: add the parameter to the query string to retrieve the metrics available for the goal and ads (when expanded), and/or the projected delivery for the goal at the time of the request. Possible values are metrics and projections.
    • Add embed=metrics to the query string to retrieve all the available metrics.
    • Add embed=metrics&metrics=<value> to the query string to retrieve one or several specific metrics. Possible values are:
      • impression
      • clickThrough
      • start
      • firstQuartile
      • midpoint
      • thirdQuartile
      • complete
      • delivered
      • ctr (only returned on goals)
      • completionRate (only returned on goals)
      • ecpm (only returned on goals)

      For example: embed=metrics&metrics=impression&metrics=clickThrough&metrics=complete

    • Add embed=projections to the query string to retrieve the projected delivery for the goal at the time of the request. Projected delivery is only available for goals.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: see goals in the Response Body Format. The response only contains one goal object without the pagination element.

Example - No Expanded Objects:

Request header:

GET /v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e?embed=projections&embed=metrics HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
    "campaign": {
        "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
        "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
    },
    "name": "Ooyala summer goal II/II",
    "description": "Ooyala summer goal II/II",
    "target": {
        "value": 250000,
        "unit": "impression"
    },
    "start": "2018-08-15T22:00:00Z",
    "end": "2018-09-15T22:00:00Z",
    "pricing": {
        "value": 10,
        "pricingModel": "cpm"
    },
    "ads": [
        {
            "id": "e9fc0519-b807-42fe-a101-bd7c65eea957",
            "href": "https://api.videoplaza.com/v3/ads/e9fc0519-b807-42fe-a101-bd7c65eea957"
        }
    ],
    "type": "impression",
    "deleted": false,
    "priority": {
        "value": 4,
        "origin": {
            "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
            "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
            "entity": "campaign"
        }
    },
    "metrics": {
        "impression": 0,
        "clickThrough": 0,
        "start": 0,
        "firstQuartile": 0,
        "midpoint": 0,
        "thirdQuartile": 0,
        "complete": 0,
        "delivered": 0,
        "ctr": 0,
        "completionRate": 0,
        "ecpm": 10
    },
    "customId": "Custom goal ID",
    "adPosition": "any",
    "goalSequence": {
        "sequence": 2,
        "totalAmountOfGoals": 2,
        "sequenceScope": "lifetime"
    },
    "projectedDelivery": 0,
    "skipSettings": {
        "value": {
            "showWhen": "afterFirstUnique",
            "resetAfter": 12,
            "skipOffset": {
                "value": 5,
                "unit": "seconds"
            },
            "parentOverride": true
        },
        "origin": {
            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "entity": "goal"
        }
    },
    "cap": {
        "capType": "dailyCap",
        "capValue": 11000
    },
    "frontload": {
        "value": 30,
        "origin": {
            "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
            "entity": "site"
        }
    },
    "goalMode": "normal"
}

Example - Expanded Objects:

Request header:

GET /v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e?expand=ads&embed=projections&embed=metrics HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: -

Success response:

HTTP status:
  200 (OK)

Body:
{
    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
    "campaign": {
        "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
        "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
    },
    "name": "Ooyala summer goal II/II",
    "description": "Ooyala summer goal II/II",
    "target": {
        "value": 250000,
        "unit": "impression"
    },
    "start": "2018-08-15T22:00:00Z",
    "end": "2018-09-15T22:00:00Z",
    "pricing": {
        "value": 10,
        "pricingModel": "cpm"
    },
    "ads": [
        {
            "id": "e9fc0519-b807-42fe-a101-bd7c65eea957",
            "name": "Ooyala mid-roll ad",
            "creative": {
                "insertionPoint": "midroll",
                "asset": {
                    "id": "f24ce53c-f714-4820-9dbf-aa1bc578facb",
                    "href": "https://api.videoplaza.com/v1/assets/f24ce53c-f714-4820-9dbf-aa1bc578facb"
                },
                "clickDestinationUri": "http://ooyala.com",
                "type": "standard"
            },
            "enabled": true,
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0
            },
            "description": "Ooyala mid-roll ad",
            "weight": {
                "proportional": true,
                "totalOverridden": 0,
                "value": 1
            },
            "customId": "Custom ad ID",
            "start": {
                "value": "2018-08-15T22:00:00Z",
                "origin": {
                    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "entity": "goal"
                }
            },
            "end": {
                "value": "2018-09-15T22:00:00Z",
                "origin": {
                    "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
                    "entity": "goal"
                }
            },
            "externalTrackers": [
                {
                    "id": "7c0411b9-ef75-4c09-8ccc-e1108e2b3152",
                    "url": "http://start-tracking.com",
                    "event": "start"
                },
                {
                    "id": "a6c6f4d4-55c3-4107-aa32-0029b9c3af50",
                    "url": "http://pause-tracking.com",
                    "event": "pause"
                }
            ],
            "deviceContainers": [
                {
                    "id": "145299c6-ba02-45de-9995-c2dfaba44c8c"
                },
                {
                    "id": "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
                }
            ],
            "created": "2018-07-20T08:36:05Z",
            "modified": "2018-07-20T08:36:05Z"
        }
    ],
    "type": "impression",
    "deleted": false,
    "priority": {
        "value": 4,
        "origin": {
            "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
            "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da",
            "entity": "campaign"
        }
    },
    "metrics": {
        "impression": 0,
        "clickThrough": 0,
        "start": 0,
        "firstQuartile": 0,
        "midpoint": 0,
        "thirdQuartile": 0,
        "complete": 0,
        "delivered": 0,
        "ctr": 0,
        "completionRate": 0,
        "ecpm": 10
    },
    "customId": "Custom goal ID",
    "adPosition": "any",
    "goalSequence": {
        "sequence": 2,
        "totalAmountOfGoals": 2,
        "sequenceScope": "lifetime"
    },
    "projectedDelivery": 0,
    "skipSettings": {
        "value": {
            "showWhen": "afterFirstUnique",
            "resetAfter": 12,
            "skipOffset": {
                "value": 5,
                "unit": "seconds"
            },
            "parentOverride": true
        },
        "origin": {
            "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e",
            "entity": "goal"
        }
    },
    "cap": {
        "capType": "dailyCap",
        "capValue": 11000
    },
    "frontload": {
        "value": 30,
        "origin": {
            "id": "301af24d-d8bf-4ddf-985a-c94cdf254ebb",
            "entity": "site"
        }
    },
    "goalMode": "normal"
}
https://help.ooyala.com/sites/all/libraries/dita/en/video-advertising/oadtech/ad_serving/dg/rest_goal_query.html

Was this article helpful?