You are here: Developers > OpenX Platform API > Platform API reference > report service

report service

Last updated on February 8, 2018

The report service allows you to make a single API request to set the report date range, select report attributes, and generate a report.

If you are unfamiliar with OpenX reporting, please refer to the OpenX Reporting documentation for more detailed information about how reports are managed in the user interface.

The report service provides the following endpoints:

Listing reports

GET /report/get_reportlist

List all reports that are available to you based on your account and user permissions.

Using this list of accessible reports, you can select and run the report which contains the information you need.

A list of report codes is listed below, however, use GET /report/get_reportlist to list the reports you have permission to access.

Sample request

curl http://PUBLISHER-ui.openx.net/ox/4.0/report/get_reportlist

Sample response

{
   "content": [
      {
         "acl_resource_type": "inventory", 
         "code": "adunit_sum", 
         "context": "inventory", 
         "context_display_name": "Inventory", 
         "description": "The Ad Unit Summary report is designed to show delivery summary by ad unit for the specified date range.", 
         "title": "Ad Unit Summary"
      }, 
      {
         "acl_resource_type": "inventory", 
         "code": "cust_keyval", 
         "context": "inventory", 
         "context_display_name": "Inventory", 
         "description": "The Custom Key Value report is designed to show delivery activity across the pre-defined custom key value
            for a specified date range. This report helps users understand volume, sales, and performance information broken up 
            by individual custom key values.", 
         "title": "Custom Key Value"
      }
   ], 
   "lang": "en", 
   "status": "OK"
}

Response data

Parameter Description
content

List of all accessible reports which includes the type of report, report code, description of the report, and report title.

lang

Language of the UI instance.

status

Status of the generated report.

Some users set a timeout for their API requests, and report results are not available before the timeout setting. For this reason, the API is designed to provide the current status before the report has completed. Possible values include:

  • OK = Report was completed and the results are ready for pickup.
  • QUEUED = Report request was received, is in the reporting queue, and will be processed shortly. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • RUNNING = Report request was received and is still running. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • TIME OUT = Indicates a timeout state. Only possible when requesting a JSON report.

Report codes

API Report Name

UI Report

Description
adunit_size_sum

Exchange Revenue

Ad Unit Size Summary report displays a delivery summary by ad unitThe smallest inventory component that represents the space on a site where ads display. size for a specified date range.

This report is a component of the Exchange Revenue report.

adunit_sum

Exchange Revenue

Ad Unit Summary report displays a delivery summary by ad unit for a specified date range.

This report is a component of the Exchange Revenue report.

aud_inv

Audience Segment by Site

The Audience SegmentA group of users with similar traits or characteristics. by SiteAn OpenX component that represents top-level domains or subdomains and is used to organize ad units. Sites enable you to target and report on inventory performance. report provides a time-based view of audience distribution across sites.

Note: Requires Audience product. This is a legacy report and does not contain revenue metrics.

aud_sum

Audience Segment by Account

The Audience Segment by Account report provides day-by-day audience segment analysis, including segment size and daily reach.

Note: Requires Audience product. This is a legacy report and does not contain revenue metrics.

bid_perf

Bid Performance

The Bid Performance report provides insights into bid activity based on inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit., demand, and Private MarketplaceThe packaging, offering, and selling of high quality inventory to a limited set of buyers. Abbreviated as PMP. deal information. Report-specific parameters allow you to evaluate both Ad Exchange and Private Marketplace performance.
buyer_sum

Exchange Revenue

The BuyerA company that pays a demand partner to purchase ad inventory on OpenX Ad Exchange. Summary report displays a delivery summary by buyer for a specified date range.

This report is a component of the Exchange Revenue report.

cust_keyval

Custom Key Value

The Custom Key Value report displays delivery activity across the predefined custom key values for a specified date range. This report helps you understand volume, sales, and performance information broken up by individual custom key values.

Note: Requires whitelisted custom key values. This is a legacy custom key value report and does not contain revenue metrics.
There is a new version of Custom Key Value report in the My Reports UI with additional fields – but not yet available in the API.

exch_perf

Exchange Revenue

The Exchange Performance report provides insights into how your inventory performs in OpenX Exchange.

This report is a component of the Exchange Revenue report.

inv_bill

Ad Server

The Platform Billing report displays a summary of the total requests and impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions. data in UTC, broken down by Publishers, Sites and Ad Units.

This report is a component of the Ad ServerA complete digital advertising platform where publishers sell, manage, and deliver their advertising inventory across all digital formats. report.

Note: Ad Server product is required.

inv_daily_sum

Exchange Revenue

The Daily Summary report displays a delivery summary by date for a specified date range.

This report is a component of the Exchange Revenue report.

inv_del

Ad Server

Inventory Delivery displays delivery activity across various inventory dimensions to specific orders, line items, and ads for activity that occurred during a specified date range.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

inv_perf

Ad Server

The Inventory Performance report displays delivery activity across various inventory dimensions for activity that occurred during a specified date range. This report helps you understand volume, sales, and performance information by site and visitor geography.

This report is a component of the Ad Server report.

inv_perf_pub

Exchange Revenue

The Inventory Detailed Performance report displays delivery activity across various inventory dimensions for activity that occurred during a specified date range. This report helps you understand volume, sales, and performance information by site.

This report is a component of the Exchange Revenue report.

inv_rev

Ad Server

The Inventory Revenue helps you understand how revenue is spread across various dimensions of inventory, by sales channel, by day, for transactions that fit a specified date range.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

inv_sell

Ad Server

The Inventory Sell-Through report provides insight across various inventory dimensions regarding how the inventory is being sold. This report helps you to better understand which sales channels sell what volume of inventory, how each channel accounts for revenue, and how much goes unsold.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

mkt_del

Exchange Revenue

The Market Delivery report displays how each market order is delivering across particular inventory segments by time period. Only orders with activity in the given date range are shown.

This report is a component of the Exchange Revenue report.

mkt_perf

Exchange Revenue

The Market Performance report displays detailed performance information, by time period, for market orders that won impressions during the specified date range. This report helps you understand how your inventory is being sold to real-time buyers in the Market.

This report is a component of the Exchange Revenue report.

order_del

Ad Server

The Order Delivery report displays how each order (down to the line itemThe primary unit of execution for an order, which represents a specific inventory purchase and the required conditions for ad delivery. and ad levels) is delivering across particular inventory segments, by day. Only orders (or line items or ads, depending on breakout) with activity in the given date range are shown.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

order_pace

Ad Server

The Order Pacing report displays the high-level delivery status of each line item to which you have access, provided that the line item has some delivery activity in the given date range. Use this report to quickly understand the state of any given order, identify line items/orders requiring intervention, and to understand how particular orders are delivering relative to one another.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

order_perf

Ad Server

The Order Performance report displays detailed performance information, by day, for orders (down to the ad level) with activity during the specified date range. Helps you understand day-by-day delivery of an order and to gauge changes in performance. Also, this report can be shared with third parties, such as the advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. or agency.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

order_sum

Ad Server

The Order Summary report displays the high-level delivery status of each line item to which you have access, provided that the line item has some delivery activity in the given date range. Use to quickly understand the state of any given order, identify line items/orders requiring intervention, and to understand how particular orders are delivering relative to one another.

This report is a component of the Ad Server report.

Note: Ad Server product is required.

site_sum

Exchange Revenue

The Site Summary report displays a delivery summary by site for a specified date range.

This report is a component of the Exchange Revenue report.

ssp_rev

SSP Revenue

The SSPSupply-side platform, a platform or provider that allows publishers to manage and optimize revenue for their inventory from multiple sources, often in real time. Revenue report allows you to see who is buying your inventory through SSP and how much they are paying for it.

Note: SSP product is required.

video_events

Video Events

The Video Events report displays a time-based view of all VAST tracking events for video ads belonging to the advertiser with expanded VAST 3.0 engagement metrics and the inclusion of revenue.

Return to top.


Listing parameters

GET /report/get_report_inputs

Return a list of all the parameters for the specified report.

Report parameters and codes are listed and defined on the Report attributes and metrics page.

Sample request

curl http://PUBLISHER-ui.openx.net/ox/4.0/report/get_report_inputs?report=inv_perf_pub

URL parameter

Parameter

Type

Description

Required?

report

String

Report code. This value is listed as the code value within the list generated by GET /report/get_reportlist.

Required

Sample response

{
   "acl_resource_type": "inventory", 
   "content": [
      {
         "UI_input_type": "date", 
         "name": "start_date", 
         "required": "1", 
      }, 
      {
         "UI_input_type": "date", 
         "name": "end_date", 
         "required": "1", 
      }, 
   ], 
   "context": "inventory", 
   "lang": "en", 
   "report": "inv_perf_pub", 
   "status": "OK"
}

Return to top.


Running a report

GET /report/run

Run a specific report with a defined date range, report format, and set of metrics and attributes.

Note: If you change any parameters and request the same report again, it creates a new request, causing it to queue, run, and complete again.

Sample request

curl http://PUBLISHER-ui.openx.net/ox/4.0/report/run?report=inv_perf_pub&start_date=0&end_date=0&do_break=SiteName&report_format=json

URL parameters

Below are a list of generic URL parameters applicable to most reports. View Report attributes and metrics to find URL parameters specific to a report.

Parameter

Type

Description

Required?

end_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or a negative integer for the days from now. When using an integer, -7 means "until seven days from now" and 0 means "before today" (exclusive).

Required

report String

Report code. This value is listed as the code value within the list generated by GET /report/get_reportlist.

Required

start_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or an integer for the days backward from today. When using an integer, 7 means "seven days ago", 0 means "starting today" (inclusive).

Required

do_break

String

Indicate which dimensional breakouts to include in the report. Values are unique to each report.

Optional

Default: If not set, the standard main report columns appear.

report_format

String

The format of the report data to download. The possible values are:

  • csv = Comma-separated value.
  • json = JavaScript object notation format with a limitation of 1,000 rows.
  • pdf = Portable document format.
  • xls = Excel format with a limitation of 65,000 rows.

Optional

Sample response

Note: Report-specific variables (for example, column_name and name) are defined on the Report attributes and metrics page.

Response data

Parameter Description

content

URL parameters from the GET call used to generate the report.

lang

Language of the UI instance.

partialReportBody

Indicates if report data (reportBody) is complete. This field has a value of false when report data is complete.

report

Report code. This value is listed as the code value within the list generated by GET /report/get_reportlist.

report_id

OpenX identifier for a report. A report's report_id can be acquired from the response to the GET /report/run call.

For example: 3bcbd450-750a-45e6-b828-5cb448a2e374

reportBody

Report data.

reportHeader

Report header and footer information.

status

Status of the generated report.

Some users set a timeout for their API requests, and report results are not available before the timeout setting. For this reason, the API is designed to provide the current status before the report has completed. Possible values include:

  • OK = Report was completed and the results are ready for pickup.
  • QUEUED = Report request was received, is in the reporting queue, and will be processed shortly. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • RUNNING = Report request was received and is still running. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • TIME OUT = Indicates a timeout state. Only possible when requesting a JSON report.

Return to top.


Downloading a report

GET /report/download/{report_id}

Download a specific report in XLS format.

Sample request

curl http://PUBLISHER-ui.openx.net/ox/4.0/report/download/bfab5462-4bcc-497f-8801-841776e5c2b2

URL parameter

Parameter

Type

Description

Required?

report_id

report_id

OpenX identifier for a report. A report's report_id can be acquired from the response to the GET /report/run call.

For example: 3bcbd450-750a-45e6-b828-5cb448a2e374

Required

Sample response

This call will initiate a 302 redirect to an XLS download URL, for example, http://PUBLISHER-d.openx.net/pickup/adbcc707-c967-4c5d-ae03-d51f2aa15717/site_sum.xls.

Return to top.


Listing segments

GET /report/list_accounts_with_segments

List all accounts that have at least one audience segment.

Note: Listing pagination parameters (limit, offset, sort, overload) cannot be used with this endpoint.

Sample request

curl -X http://PUBLISHER-ui.openx.net/ox/4.0/report/list_accounts_with_segments

Sample response

[{
   "id": "20058ead-accf-fff1-8123-123456",
   "name": "Master Network"
}, {
   "id": "6009e7cd-accf-fff1-8123-123456",
   "name": "Test Account 1"
}, {
   "id": "600a1481-accf-fff1-8123-123456",
   "name": "VP Publisher Account 1"
}, {
   "id": "600af81c-accf-fff1-8123-123456",
   "name": "VP Publisher Account 2"
}]

Response data

Parameter Description
id

OpenX identifier for the account.

For example:

600aa500-accf-fff1-8123-b0769b

name

Name of the account.

For example: "Test Account 1"

Return to top.


Listing line item alerts

GET /report/traffic_lineitem_alerts

Return traffic line item alerts data.

The information returned from this call populates the Line Item alerts dashboard in the OpenX UI.

Sample request

curl -X http://PUBLISHER-ui.openx.net/ox/4.0/report/traffic_lineitem_alerts?overload=medium

URL parameters

Parameter

Type

Description

Required?

end_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or a negative integer for the days from now. When using an integer, -7 means "until seven days from now" and 0 means "before today" (exclusive).

Optional

limit

Integer

Number of items to list in results.

Default is 10.

Optional

offset

Integer

Beginning item in results.

Note: Must be used with limit.

Optional

overload

String

If set to light, returns only the uid for all items in results.

If set to medium, returns full objects for all items in results.

Default is medium.

Optional

sort

String

Name of a field by which results are sorted.

Note: Appending a (-) to a field name will reverse sorting order. For instance: sort=-name.

Default field is deal_priority.

Optional

start_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or an integer for the days backward from today. When using an integer, 7 means "seven days ago", 0 means "starting today" (inclusive).

Optional

Sample response

{
   "content": [{
      "status": "Running",
      "is_daily": null,
      "uid": "00049e4b-c002-fff1-8123-123456",
      "end_date": "2021-09-02 06:59:59",
      "imp": 44703,
      "remains": 183767332,
      "name": "Awesome Test Line Item",
      "osi": 5,
      "item": 297587,
      "start_date": "2012-07-24 23:07:57",
      "goal": 10000000
   }],
   "header": {
      "status": "OK",
      "platform": "350541de08dc63f93bf2731324aa390842467d57",
      "act": "012345, 987654"
   }
}

Response data

Parameter Description

act

Comma-separated list of account IDs.

content Report attributes and metrics such as line item goal, OSIOn Schedule Indicator, a metric that indicates the percentage of delivered impressions for a line item relative to the impression goal and the time elapsed in a campaign. It is defined by the following calculation: OSI = impressions-to-date/((impression_goal/(end_date - start_date + 1)) * flight_time-to-date), and line item name.

end_date

Specific date in yyyy-mm-dd HH:MM:SS format.

goal

Lifetime or daily impression goalThe maximum number of impressions to deliver for a line item in a single day (per day) or over the duration of the line item’s flight (total). When a line item reaches a daily impression goal, it is temporarily ineligible for ad selection. For example, if you set the daily impression goal to 5 and the line item reaches 5 impressions in a single day (e.g., on day 5 of a 20 day flight), then the line item is not available for ad serving for the rest of the day. However, the line item becomes eligible again for ad serving on day 6. When a line item reaches its total impression goal, no matter which day of the flight, it is no longer available for ad serving..

header

Report heading.

imp

Impressions logged.

item

OpenX ID for the line item.

name

Name of the line item.

osi

On Schedule Indicator, a metric that indicates the percentage of delivered impressions for a line item relative to the impression goal and the time elapsed in a campaignAn advertising project in its entirety, from conception through creation and buying to tracking and final analysis; A collection of related creatives with common advertising purpose and booking requirements; A set of criteria for purchasing inventory to achieve advertising goals. See order..

platform

OpenX platform ID.

remains

Number of impressions that remain to be delivered. This is calculated by subtracting imp from goal.

start_date

Specific date in yyyy-mm-dd HH:MM:SS format.

status (content)

Status of the line item.

Possible values include:

  • Active = Line item is approved, but has a future start date.
  • Expired = Line item's end date has passed.
  • Paused = Line item is temporarily suspended.
  • Pending = Line item is created, but not yet approved.
  • Running = Line item is created and its start date has already passed.

status (header)

Status of the generated report.

Some users set a timeout for their API requests, and report results are not available before the timeout setting. For this reason, the API is designed to provide the current status before the report has completed. Possible values include:

  • OK = Report was completed and the results are ready for pickup.
  • QUEUED = Report request was received, is in the reporting queue, and will be processed shortly. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • RUNNING = Report request was received and is still running. You can request the same report again (without changing any parameters). This causes the report to provide the data as soon as the first request completes.
  • TIME OUT = Indicates a timeout state. Only possible when requesting a JSON report.

uid

OpenX ID for the line item.

Return to top.


Listing impressions

GET /report/traffic_by_account_time

Return account impressions over a specified time range.

The information returned from this call populates the Impressions by date dashboard in the OpenX UI.

Sample request

curl -X http://PUBLISHER-ui.openx.net/ox/4.0/report/traffic_by_account_time?start_date=2&end_date=0

URL parameters

Parameter

Type

Description

end_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or a negative integer for the days from now. When using an integer, -7 means "until seven days from now" and 0 means "before today" (exclusive).

start_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or an integer for the days backward from today. When using an integer, 7 means "seven days ago", 0 means "starting today" (inclusive).

Sample response

{
   "content": [{
      "active": 758,
      "click-imp": 0.00094600000000000001,
      "conv": 0,
      "req": 10176304,
      "rev": "5.04",
      "spend": "5.04",
      "imp": 105609,
      "conv-click": 0,
      "b_imp": 347,
      "date": "2017-06-15",
      "coin": "USD",
      "eRPM": 14.522726,
      "click": 1
   }, {
      "active": 758,
      "click-imp": 0.0025869999999999999,
      "conv": 0,
      "req": 10040535,
      "rev": "2.47",
      "spend": "2.47",
      "imp": 77308,
      "conv-click": 0,
      "b_imp": 290,
      "date": "2017-06-16",
      "coin": "USD",
      "eRPM": 8.5254619999999992,
      "click": 2
   }],
   "header": {
      "status": "OK",
      "revshareread": "1",
      "account": "123456,123457,12348",
      "tz": "America/New_York",
      "start_time": "1497499200",
      "platform": "350541de08dc63f93bf2731324aa3908429876543",
      "end_time": "1498103999"
   }
}

Response data

Parameter Description

account

IDs of accounts included in the data.

active

Number of active orders.

b_imp

Total number of billable impressions for the advertiser account.

click

Total number of clicks.

click-imp

Click-through rate.

coin

Currency used for transactions, such as USD, Euro.

content Report attributes and metrics such as number of active orders, CTRClick-through rate, the percentage of impressions that results in a click through. For example if a banner was clicked on 87 times after being shown 1000 times, it would have a CTR or click-through rate of .087 or 8.7% (87/1000 = 0.087×100 = 8.7)., and number of active orders.

conv

Total number of conversions.

conv-click

Click conversion rateThe percentage of visitors to a website who sign up for advertised offers or buy advertised products. Proven high conversion ratios (via web analytics) add value to a website’s inventory..

date

Date of aggregated data in the format: YYYY-MM-DD.

end_date

Final date of data set timeframe.

eRPM

Effective revenue per thousand ad impressions.

header

Report header information.

imp

Total number of ads that have been served.

platform

Platform ID or instance ID.

req

Total number of requests for the list of publisherAn account type that represents a business with ad space to sell.'s segment ids.

rev

Revenue generated by the list of site IDs for a given time range.

revshareread

Inclusion or exclusion of revenue share.

  • 0 = Exclude revshare of the network.
  • 1 = Include revshare of the network.

Default: 0

spend

Total money spent on the order.

start_date

Starting date of data set timeframe.

status

Status of the report.

tz

Timezone of the instance.

Return to top.


Listing order impressions

GET /report/traffic_by_order

Return account impressions over a specified time range by order.

The information returned from this call populates the Order History dashboard in the OpenX UI.

Sample request

curl -X http://PUBLISHER-ui.openx.net/ox/4.0/report/traffic_by_order?overload=medium&start_date=1&end_date=1

URL parameters

Parameter

Type

Description

Required?

end_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or a negative integer for the days from now. When using an integer, -7 means "until seven days from now" and 0 means "before today" (exclusive).

Optional

overload

String

If set to light, returns only the uid for all items in results.

If set to medium, returns full objects for all items in results.

Default is medium.

Optional

start_date

Date

Integer

Specific date in yyyy-mm-dd HH:MM:SS format or an integer for the days backward from today. When using an integer, 7 means "seven days ago", 0 means "starting today" (inclusive).

Optional

Sample response

{
   "content": [{
      "active": 758,
      "click-imp": 0.00094600000000000001,
      "conv": 0,
      "req": 10176304,
      "rev": "5.04",
      "spend": "5.04",
      "imp": 105609,
      "conv-click": 0,
      "b_imp": 347,
      "date": "2017-06-15",
      "coin": "USD",
      "eRPM": 14.522726,
      "click": 1
   }, {
      "active": 758,
      "click-imp": 0.0025869999999999999,
      "conv": 0,
      "req": 10040535,
      "rev": "2.47",
      "spend": "2.47",
      "imp": 77308,
      "conv-click": 0,
      "b_imp": 290,
      "date": "2017-06-16",
      "coin": "USD",
      "eRPM": 8.5254619999999992,
      "click": 2
   }],
   "header": {
      "status": "OK",
      "revshareread": "1",
      "account": "123456,123457,12348",
      "tz": "America/New_York",
      "start_time": "1497499200",
      "platform": "350541de08dc63f93bf2731324aa3908429876543",
      "end_time": "1498103999"
   }
}

Response data

Parameter Description

account

IDs of accounts included in the data.

active

Number of active orders.

b_imp

Total number of billable impressions for the advertiser account.

click

Total number of clicks.

click-imp

Click-through rate.

coin

Currency used for transactions, such as USD, Euro.

content Report attributes and metrics such as number of active orders, CTR, and number of active orders.

conv

Total number of conversions.

conv-click

Click conversion rate.

date

Date of aggregated data in the format: YYYY-MM-DD.

end_date

Final date of data set timeframe.

eRPM

Effective revenue per thousand ad impressions.

header

Report heading.

imp

Total number of ads that have been served.

platform

Platform ID or instance ID.

req

Total number of requests for the list of publisher's segment ids.

rev

Revenue generated by the list of site IDs for a given time range.

revshareread

Inclusion or exclusion of revenue share.

  • 0 = Exclude revshare of the network.
  • 1 = Include revshare of the network.

Default: 0

spend

Total money spent on the order.

start_date

Starting date of data set timeframe.

status

Status of the report.

tz

Timezone of the instance.

Return to top.

See also

Feedback form