Ad Query Requests

Use the Ad Query API to retrieve detailed information and perfomance metrics from ads.

Getting Started

  • Base URL: https://api.videoplaza.com/v3/ads.
  • 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 - Ads
  • Related user documentation:
The Ad Query endpoints allow you to:

Query for Multiple Ads

This endpoint enables you to list all ads associated with your account. Various query parameters allow you to get very detailed and specific information on a subset of ads that match your query, all within one API call. You can also embed metrics to quickly retrieve one, several, or all available metrics for the listed ads. 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/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params
Note: All query parameters are optional.
  • embed: add the parameter to the query string to retrieve the metrics available for the ads.
    • Add embed=metrics to the query string to retrieve all the available metrics.
    • Add embed=metrics&metrics=<value> to the query string to retrieve only specific metrics. Possible values are:
      • impression
      • clickThrough
      • start
      • firstQuartile
      • midpoint
      • thirdQuartile
      • complete
      • delivered
  • ads.created.before: filter on ads created before a specific date and time in the results. See Date and Time Format on how to format this field.
  • ads.created.after: filter on ads created after a specific date and time in the results. See Date and Time Format on how to format this field.
  • goal.id: filter on ads associated with a specific goal based on that goal's ID. You can only filter on a single goal.
  • pageSize: enter the number of ads 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 ads in the Response Body Format.

Example:

Request header:

GET /v3/ads?ads.created.after=2018-07-19T00:00:00Z&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:
{
    "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,
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "goal": {
                "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
                "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e"
            },
            "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"
        },
        {
            "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,
            "campaign": {
                "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
                "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
            },
            "goal": {
                "id": "e26d57f8-ba36-422e-8730-8b7e44311d9f",
                "href": "https://api.videoplaza.com/v3/goals/e26d57f8-ba36-422e-8730-8b7e44311d9f"
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0
            },
            "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"
        },
        {
            "id": "a8ba0677-4e9e-4d65-a7ed-e5be2ef2a289",
            "name": "Sponsor ad",
            "creative": {
                "insertionPoint": "preroll",
                "type": "standardPlaceholder"
            },
            "enabled": true,
            "campaign": {
                "id": "b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3",
                "href": "https://api.videoplaza.com/v3/campaigns/b8d44a5e-6e1d-42a5-a5fd-cb504cf514a3"
            },
            "goal": {
                "id": "4866d0b3-2686-4fed-a87a-8f419cf5c935",
                "href": "https://api.videoplaza.com/v3/goals/4866d0b3-2686-4fed-a87a-8f419cf5c935"
            },
            "metrics": {
                "impression": 0,
                "clickThrough": 0,
                "start": 0,
                "firstQuartile": 0,
                "midpoint": 0,
                "thirdQuartile": 0,
                "complete": 0,
                "delivered": 0
            },
            "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"
        }
    ],
    "pagination": {
        "totalCount": 3,
        "pageSize": 10,
        "pageNumber": 1
    }
}

Query for One Ad

This endpoint enables you to get one ad associated with your account. You can also embed metrics to quickly retrieve one, several, or all available metrics for an ad. The available query parameters are described in detail in the table below.

Method GET
URL /v3/ads/{adId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params adId: the ID of the ad
Query params
  • embed: add the parameter to the query string to retrieve the metrics available for the ad.
    • Add embed=metrics to the query string to retrieve all the available metrics.
    • Add embed=metrics&metrics=<value> to the query string to retrieve only specific metrics. Possible values are:
      • impression
      • clickThrough
      • start
      • firstQuartile
      • midpoint
      • thirdQuartile
      • complete
      • delivered
Body -
Success response

HTTP status: 200 OK

Header: -

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

Example:

Request header:

GET /v3/ads/e9fc0519-b807-42fe-a101-bd7c65eea957?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": "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,
    "campaign": {
        "id": "57e239e6-003d-4c01-804f-695d05fdd5da",
        "href": "https://api.videoplaza.com/v3/campaigns/57e239e6-003d-4c01-804f-695d05fdd5da"
    },
    "goal": {
        "id": "80028bd7-95d3-4d89-8945-6d0801b5c03e",
        "href": "https://api.videoplaza.com/v3/goals/80028bd7-95d3-4d89-8945-6d0801b5c03e"
    },
    "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"
}
https://help.ooyala.com/sites/all/libraries/dita/en/video-advertising/oadtech/ad_serving/dg/rest_ad_query.html

Was this article helpful?