Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Excerpt Include
ex:api token warning
ex:api token warning
nopaneltrue

The PubMatic Analytics API lets you view and interact with data insights to improve ad performance. You can easily integrate PubMatic APIs using simple HTTP GET requests to the PubMatic Analytics API Server. Mandatory and optional parameters in the query string such as dimensions, metrics, and filters let you control the scope of the JSON results PubMatic returns. The API provides methods that let you query bulk-data in four categories:

  1. Publisher : use to constrain queries to a specific publisher's data.
  2. Buyer : use to constrain queries to a specific buyer's data.
  3. DSP : use to constrain queries to a specific DSP's data.




Link to Definition

/v1/analytics/data/publisher/{publisherId}

GET

Access bulk data details for a specific publisher.

Get the Bulk-Data Details for a Publisher

/v1/analytics/data/buyer/{buyerId}

GET

Access bulk-data details for a specific buyer.

Get the Bulk-Data Details for a Buyer

/v1/analytics/data/dsp/{dspId}

GET

Access bulk-data details for a specific DSP.

Get the Bulk-Data Details for a DSP


Info
titleTime-To-Live for Data (TTL)

Daily: The API Data Pull supports daily data for the last 90 days.
Monthly: The API Data Pull supports monthly data for the last 13 months.

Get the Bulk-Data Details for a Publisher

Access bulk data details for a specific publisher. 

Request

URI

http://${URI_PREFIX}/v1/analytics/data/publisher/{publisherId}

HTTP Method

GET

Excerpt Include
ex:URI_Prefix Placeholder Reminder
ex:URI_Prefix Placeholder Reminder
nopaneltrue

Request Headers

Header Name

Type

Value

Required

Description

Authorization

String 

Bearer

${access_token}

Yes

Send your generated access token in place of ${access_token} for authentication. Example:

curl "http://api.pubmatic.com/v1/analytics/data/publisher/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=revenue,paidImpressions,ecpm&pageSize=10&sort=-revenue&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"

Request Path Parameters

Name

Type

Required

Validations

Description

publisherId

Integer

Yes

Publishers can only query their own data.

Indicates the publisher ID.

Request Query Parameters

Excerpt Include
EX:API Data Pull - Request Query Parameters Excerpt
EX:API Data Pull - Request Query Parameters Excerpt
nopaneltrue

Response

Header Name

Type

Description

Content-Type

application/json

JSON response

Response Body Parameters

Excerpt Include
EX:API Data Pull - Response Body Parameters Excerpt
EX:API Data Pull - Response Body Parameters Excerpt
nopaneltrue

Code Block
languagexml
titleSample JSON
linenumberstrue
collapsetrue
{
  "columns": [
    "date",
    "paidImpressions",
    "revenue"
  ],
  "rows": [
    [
      "2016-06-01",
      25249100,
      42000.554432
    ],
    [
      "2016-06-02",
      28841014,
      51154.094958
    ],
    [
      "2016-06-03",
      25200705,
      63640.230188
    ],
    [
      "2016-06-04",
      35254500,
      71632.23456
    ],
    [
      "2016-06-05",
      237219940,
      87654.32123
    ]
  ],
  "displayValue": {
    "date": {
      "2016-06-02": "2016-06-02",
      "2016-06-01": "2016-06-01",
      "2016-06-05": "2016-06-05",
      "2016-06-03": "2016-06-03",
      "2016-06-04": "2016-06-04"
    }
  },
  "currency": "USD",
  "alert": null,
  "dataFreshness": {
    "dataFreshnessHour": "2016-06-16T05",
    "timeZone": "PST"
  }
}

HTTP Status Codes

The table below lists common HTTP status codes sent in REST API responses from the PubMatic API platform.

Status

Message

Type

Description

200

OK

success

The request has been successfully processed; check contents of body.

400

Bad Request

client-side error

There is some validation failure; check the response body for error details.

401

Unauthorized


There is an authentication or authorization failure; check the response body for specific details.

403

Forbidden


You are not subscribed to this feature of the Platform.

404

Not Found


The server does not have this resource.

413

Request Entity Too Large


The request content exceeds the size limit.  This may be the number of records or the actual content size.

500

Internal Server Error

API-side error

There is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

Available Dimensions

Dimensions are attributes, such as Country, Platform, and Site, available in the PubMatic system. The following tables provide information about dimension grouping.

Dimensions for Historic Data

Dimension ID

Data Type

Description

adFormatId 

numeric

Type of Ad associated with the impression (e.g., video display)

adNetworkGroupId  

numeric

Name of the parent Ad Network that monetized the impression.

adNetworkVariantId 

numeric

Name of the parent Ad Network's campaign that monetized the impression.

pbReason

numeric

Reason for Passback.

tldEntity

numeric

Top level domain Entity. Applicable in the case of mobile impressions.

tldId

numeric

Top level domain.

adSizeId

numeric

Size of the ad associated with the impression (e.g., 200 x 800)

adTagId

numeric

Name of the ad tag used when an impression was requested.

advertiserCategoryId

numeric

Category of the advertiser.

advertiserId 

numeric

Name of the advertiser associated with the ad. Advertisers spending on "Reseller" will appear as "Reseller - Advertiser" for DSP and Buyers.

atdId

numeric

Name of the agency, ATD or buyer associated with the DSP that won the impression.

campaignId

numeric

Campaign of the advertiser associated with the ad.

categoryId

numeric

Category of the site from which an impression was requested.  

channelId

numeric

Sales channel through which the impression was won (e.g., RTB, PMP).

cookied 

boolean

Indicates whether or not the DSP's cookies were dropped when an impression was requested.

countryId 

numeric

Country from which an impression was requested. (Refer to How Countries are Reported in Analytics Reports for more information)

Info

This dimension is not available in hourly view. You must query using date range only. 


creativeId

numeric

The creative id delivered in the ad response. This applies to video ads ONLY.

date

string

Date (YYYY-MM-DD format) on which an impression was requested.

dealMetaId

numeric

Name of the Marketplace Deal that won the impression.
This is the numeric ID that the PubMatic system uses to track the Deal

Info
titleNote

This dimension can only be combined with the following dimensions:

  • Ad Format
  • Ad Size
  • Advertiser
  • Buyer
  • Category
  • DSP
  • Platform
  • Site
  • Date
  • Hour


domainId  

numeric

Domain name (web addresses) of the advertiser. The domains are identified by the landing page of the impression displayed.

dspId

numeric

Name of the DSP that won the impression.

foldPositionId 

numeric

Fold placement associated with the ad tag used when an impression was requested.

hour

string

Time (YYY-MM-DD'T'HH format) at which an impression was received.

mobDeviceIdFlag

boolean

Indicates whether the visitor's Device ID is present in the impression requests.

mobDeviceIdTypeId

boolean

Type of Device ID used by the visitor to generate an impression request. 

mobDeviceTypeId 

boolean

Type of Device used by the visitor to generate an impression request. 

mobGeoSourceFlag

boolean

Source that provided the visitor's geographical location.

mobLatLongFlag

boolean

Indicates whether the visitor's latitude/longitude details were included in the impression request.

mobMakeModelId

numeric

Mobile Make/Model Id.

mobOsId  

numeric

Mobile Operating System Id.

month

string

Month (YYYY-MM format) at which an impression was  received .

platformId 

numeric

Platform through which an impression was requested (e.g., Web, Mobile Web)

publisherDealId 

string

The Publisher Deal Id. This is the alphanumeric value that is used by publishers which is also sent over RTB pipes.

Info

publisherDealId is currently only supported when the request also contains dealMetaId. 
Example: dimensions=dealMetaId,publisherDealId will return a column for dealMetaId another for publisherDealId and then the metrics.
Sending this dimension standalone isn't currently supported.


sectionId

numeric

Section of the site from which an impression was requested.

secureStatus

boolean

Indicates whether the inventory is secure.

siteId

numeric

ID of the site from which an impression was requested.

videoClientId

numeric

This will be present when a video tracker (e.g. event, impression, error) is fired by the PubMatic VPAID component. This ID will represent whether it is a Flash VPAID component (1) or HTML/JS VPAID component (2), otherwise if not present (NULL) it means the PubMatic VPAID component was not present.

videoErrorId 

numeric

Video Error Code. Includes the IAB VAST error codes along with PubMatic custom video error codes that provide more granularity for debugging.

videoEventId

numeric

Event id represents the type of video tracker event that was fired by the video player. Events can include start event, click event, 25%, 50%, completion, etc.


Info
titleNot all dimensions and metrics are supported together…

For more information and verification, log in to PubMatic Analytics UI.

Dimensions for Rule Data (RTB Rules Report in MBC Analytics)

Dimension ID

Data Type

Description

campaignId 

numeric

Campaign of the advertiser associated with the ad.

date

string

Date (YYYY-MM-DD format) on which an impression was requested.

pubId

integer

Publisher associated with the impression requests.

ruleId

numeric

Winning Rule ID and Ad Server logs.

ruleMetaId

numeric

Rule Meta ID for PMPF rule type.

siteId

numeric

ID of the site from which an impression was requested.

Dimensions for Identity data

Dimension IDData typeDescription
datestringDate (YYYY-MM-DD format) on which an impression was requested.
pubIdintegerPublisher associated with the impression requests.

adFormatId 

numeric

Type of Ad associated with the impression (e.g., video display).

platformId 

numeric

Platform through which an impression was requested (e.g., Web, Mobile Web).

Browser IdBrowserIdnumericBrowser through which an impression was requested (e.g., Chrome, Safari, Firefox).
GDPR ConsentGDPRConsentnumericIndicates whether GDPR consent is provided or not (where applicable).
Partner Id PartnerId numericIdentity Partner (for example, TTD ID, Criteo ID, PubCommon ID).
IdentityPartnerFlagstringIndicates whether the Identity information is received in the impression (Yes/No).
PubToPubmaticCookienumericIndicates whether the publisher to PubMatic cookie data is received in the impression (Yes/No).
dspidintegerIndicates the DSP ID.
PubmaticToDspCookiestringindicates whether the DSP cookie data is available for the impression (Yes/No).

Available Metrics

The following tables list available metrics for publisher bulk-data.

Metrics for Historic Data

Metric ID

Data Type

Description

avgPubmaticBidsEcpmnumericAverage CPM of the bid responses from Pubmatic

averageBidEcpmAdv

numeric

Average CPM of the bid responses associated with an advertiser.  

averageBidEcpmAtd

numeric

Average CPM of the bid responses associated with a buyer.  

averageBidEcpmDsp 

numeric

Average CPM of the bid responses received from a DSP. 

pbImpressions

numeric

Number of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system.

bidPercentageDsp

numeric

Number of bids responded as % of bid request sent. Formula : bidPercentageDsp = ( nonZeroBidResponses / totalBidsRequests ) * 100   

bidWinRateAdv

numeric

Rate of won bids expressed as a percentage of total bids for advertiser. Formula : bidWinRateAdv = paidImpressions * 100 / nonZeroBidReceived

bidWinRateAtd 

numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage. Formula :(Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateDsp

numeric

A DSP's paid impressions divided by non-zero bid responses, expressed as a percentage.Formula: (Paid Impressions * 100) / Non-Zero Bid Responses

clicks

numeric

Number of paid impressions clicked by users.   

ctr

numeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed. Formula :clicks / paidImpressions *100

defaults

numeric

Number of impressions not served (defaulted) by an ad network configured in the PubMatic system. 

ecpm

numeric

Average CPM (cost per thousand) for the impressions.

fillRate 

numeric

Percentage of times an ad is displayed to the visitor. Higher rates are better.

gEcpm

numeric

Gross eCPM

lostBidsAmountByAuction

numeric

Amount of the bid responses that lost to the winning bid response in the auction.

lostBidsAmountByBlockList 

numeric

Amount of the bid responses that lost to the winning bid response in the Brand Control blocklist.

lostBidsAmountByCBLK 

numeric

Lost Bid Amount (Creative Block)

lostBidsAmountByDWLF

numeric

Amount of the bid responses that lost because the advertiser's associated category/name/domain was not included in the Marketplace deals.

lostBidsAmountByFloor

numeric

Amount of the bid responses that lost because their value was below the floor set in the Marketplace Rule Manager. 

lostBidsByAuction

numeric

Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  

lostBidsByBlockList

numeric

Number of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s allowlist. 

lostBidsByCBLK  

numeric

Lost Bid Count (Creative Block)

lostBidsByDWLF

numeric

Number of bid responses that did not win the impression because the associated Marketplace deal's allowlist did (DWLF) not include the advertiser.

lostBidsByFloor 

numeric

Number of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.     

lostBidsEcpmAdv

numeric

Average CPM of the bid responses associated with an advertiser.  

lostBidsEcpmAtd 

numeric

Average CPM of the bid responses associated with a buyer.

lostBidsEcpmByAuction

numeric

eCPM of the bid responses that lost to the winning bid response in the auction. 

lostBidsEcpmByBlockList

numeric

eCPM of the bid responses that lost because the advertiser's associated category/name/domain was added in the Brand Control blocklist. 

lostBidsEcpmByDWLF

numeric

eCPM of the bid responses that lost because the advertiser'sassociated category/name/domain was not included in the Marketplace deals' allowlist. 

lostBidsEcpmByFloor

numeric

eCPM of the bid responses which lost because their value was below the floor set in the Marketplace Rule Manager.

lostBidsEcpmDsp 

numeric

eCPM of the bid responses associated with a DSP that lost the impressions.  

lostBidsTotalAmount 

numeric

Total amount of the bid responses that lost due to a reason other than that described in the Lost Bids Amount (Auction) metric. 

measuredImpressions

numeric

Number of impressions measured by IAS 

netRevenuenumericNet Revenue. Applicable to only the publishers with net bidding enabled. This number is not for billing purpose, but an estimate.
netEcpmnumericNet eCPM. Applicable to only the publishers with net bidding enabled. This number is not for billing purpose, but an estimate.

nonZeroBidReceived

numeric

Number of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually. 

nonZeroBidResponses

numeric

Number of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.

paidImpressions

numeric

Number of impressions won by the demand partner.

pbImpressionsBot

numeric

Number of impressions passed back to the publisher because requests came from a Web bot.

pbImpressionsNet 

numeri

Number of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system. 

pbImpressionsNonApproved 

numeric

Number of impressions passed back to the publisher because its site URL was either not included in the publisher's allowlisted domains or included in the global supply-side blocklist.  

percentInViewForMoreThan15sec

numeric

(%) of Ad in viewable area more than 15 seconds.

percentInViewForMoreThan5sec 

numeric

(%) of Ad in viewable area more than 5 seconds.

pubmaticBidAmountnumericPotential revenue generated by all Pubmatic bid responses.

viewabilityPercent

numeric

(%) of Ad in viewable area.

phantomBids

numeric

How often PubMatic bid response loses to others.

revenue 

numeric

Gross Revenue amount generated by the winning impressions.

ssExpectedRevenue

numeric

Gross Potential revenue generated by all PubMatic bid responses.

ssWinningImpressionsnumericNumber of non-zero responses to the publisher. This metric shows the impression requests for which Pubmatic responded with nonzero bid responses.

suspiciousImpressions 

numeric

Number of impressions marked as suspicious by IAS

totalBidAmount

numeric

Amount of the total bid responses received by the PubMatic system.Formula: Total bid responses * Avg. bid eCPM

totalBidsRequestsDsp

numeric

Total number of bid requests sent by PubMatic to a DSP.

totalImpressions

numeric

Total number of impressions sent by the publisher to the PubMatic system. This value does not include the number of defaulted impressions.

totalLostBidsAdv

numeric

Total number of advertiser bid responses that did not win the impressions. 

totalLostBidsAtd 

numeric

Total number of buyer bid responses that did not win the impressions. 

totalLostBidsDsp

numeric

 Total number of DSP bid responses that did not win the impressions.

totalRequests 

numeric

Total Requests.

vctr  

numeric

Click Through Rate

video25PercentCount

numeric

25% Video Count 

video50PercentCount

numeric

50% Video Count  

video75PercentCount

numeric

75% Video Count

videoClicksCount   

numeric

Video Click Count 

videoCompleteCount 

numeric

Video Complete Count 

videoErrorCount

numeric

Video Error Count

videoEventCount 

numeric

Error Count

videoImpressions 

numeric

Video Distinct Impressions

videoStartCount

numeric

Video Start Event Count

vtr

numeric

Video Through Rate 

winningBidCountnumericNumber of non-zero bid responses to publisher. If more than one bid response is received for an impression request, this metric will account for all bid responses.

winningImpressions

numeric

Number of times PubMatic responds with a bid response

winRate 

numeric

PubMatic Paid Impressions/Total Requests

spend

numeric

Spend generated by an impression request.

Metrics for Domain Data

Metrics ID

Data Type

Description

clicks

numeric

Number of paid impressions clicked by users. 

defaults

numeric

Number of impressions not served (defaulted) by an ad network configured in the PubMatic system. 

paidImpressions

numeric

Number of impressions won by the demand partner.

pbImpressions

numeric

Number of impressions sent back to the publisher's passback networks because they were not monetized by the ad networks configured in the PubMatic system.

revenue

numeric

Gross Revenue amount generated by the winning impressions.

totalRequests

numeric

Total Requests

Metrics for Rules Data

Metrics ID

Data Type

Description

paidImpressions

numeric

Number of impressions won by the demand partner.

revenue

numeric

Gross Revenue amount generated by the winning impressions.

totalRequests

numeric

Total Requests.

Metrics for Identity data

Metric IDData typeDescription
PaidImpressionsnumeric

Number of impressions won by the demand partner .

Revenue numeric

Gross Revenue amount generated by the winning impressions.

TotalRequests
numeric

Total number of ad requests from the publisher.

PublisherBasedBidRequestCountnumericTotal number of bid requests sent by PubMatic to a DSP for the publisher for which the report(s) is being generated.

Get the Bulk-Data Details for a Buyer

Access bulk-data details for a specific Buyer.

Request

URI

http://${URI_PREFIX}/v1/analytics/data/buyer/{buyerId}

HTTP Method

GET

Request Headers

Name

Type

Value

Required

Description

Authorization

string 

Bearer ${access_token}

Yes

The access token generated for authentication should be sent in place of ${access_token}. Example:

curl "http://api.pubmatic.com/v1/analytics/data/buyer/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=spend,paidImpressions,ecpm&pageSize=10&sort=-spend&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"

Request Path Parameters

Name

Type

Required

Validations

Description

buyerId

integer

Yes

Buyers can only query their own data.

Indicates the Buyer ID.

Request Query Parameters

Excerpt Include
EX:API Data Pull - Request Query Parameters Excerpt
EX:API Data Pull - Request Query Parameters Excerpt
nopaneltrue

Response

Header Name

Type

Description

Content-Type

application/json

JSON response

Response Body

Excerpt Include
EX:API Data Pull - Response Body Parameters Excerpt
EX:API Data Pull - Response Body Parameters Excerpt
nopaneltrue
 

HTTP Status Codes

The table below lists common HTTP status codes sent in REST API responses from the PubMatic API platform.

Status

Error

Type

Description

200

OK

success

The request has been successfully processed; check contents of body.

400

Bad Request

client-side error

There is some validation failure; check the response body for error details.

401

Unauthorized


There is an authentication or authorization failure; check the response body for specific details.

403

Forbidden


You are not subscribed to this feature of the Platform.

404

Not Found


The server does not have this resource.

500

Internal Server Error

API-side error

There is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

503



Service not available or too many requests.

Available Dimensions

Dimensions are attributes, such as CountryPlatform, and Site, available in the PubMatic system. The following tables provide information about dimension grouping.

Dimensions for Historic Data

Dimension ID

Data Type

Description

averageBidEcpmAdv

numeric

Average CPM of the bid responses associated with an advertiser. 

averageBidEcpmAtd 

numeric

Average CPM of the bid responses associated with a buyer.  

bidLossRateAdv

numeric

Number of lost bids as % of total bids for Advertiser.

Formula: bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidLossRateAtd

numeric

Number of lost bids as % of total bids for ATD.

Formula: bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidPercentageAdv 

numeric

Number of non-zero bids received as % of bid received.

Formula: bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtd

numeric

Number of non-zero bids received as % of bids received.

Formula: bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidWinRateAdv 

numeric

An advertiser's paid impressions divided by non-zero bids received, expressed as a percentage.

Formula: (Paid Impressions * 100) / Non-Zero Bids Received$$

bidWinRateAtd 

numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

Formula: (Paid Impressions * 100) / Non-Zero Bids Received

clicks

numeric

Number of paid impressions clicked by users.

ctr

numeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.

Formula :(Clicks / Paid Impressions) * 100

ecpm

numeric

Average CPM (cost per thousand) for the impressions.

lostBidsByAuction

numeric

Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks). 

lostBidsByBlockList

numeric

Number of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s allowlist.

lostBidsByDWLF

numeric

Number of bid responses that did not win the impression because the associated Marketplace deal's allowlist did not include the advertiser associated with the bid. 

lostBidsByFloor

numeric

Number of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.

nonZeroBidReceived

numeric

Number of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually.

paidImpressions 

numeric

Number of impressions won by the demand partner.    

spend

numeric

Spend generated by an impression request.      

totalLostBidsAdv

numeric

Total number of advertiser bid responses that did not win the impressions.

Formula : totalLostBidsAdv = nonZeroBidReceived - paidImpressions

totalLostBidsAtd

numeric

Total number of buyer bid responses that did not win the impressions.

Formula :totalLostBidsAtd = nonZeroBidReceived - paidImpressions


Info
titleNot all dimensions and metrics are supported together…

For more information and verification, log in to PubMatic Analytics UI.

Available Metrics

The following tables list available metrics for buyer bulk-data.

Metrics for Historical Data

Metric ID

Data Type

Description

averageBidEcpmAdv

numeric

Average CPM of the bid responses associated with an advertiser. 

averageBidEcpmAtd

numeric

Average CPM of the bid responses associated with a buyer.

bidLossRateAdv

numeric

Number of non-zero bids received as % of bid received.

Formula: bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidLossRateAtd 

numeric

Number of lost bids as % of total bids for ATD.

Formula: bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidPercentageAdv

numeric

Number of non-zero bids received as % of bid received.

Formula: bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtd

numeric

Number of non-zero bids received as % of bids received.

Formula: bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidWinRateAdv

numeric

Number of non-zero bids received as % of bid received.

Formula: bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidWinRateAtd

numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

Formula : (Paid Impressions * 100) / Non-Zero Bids Received

clicks 

numeric

Number of paid impressions clicked by users.

ctr

numeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed. Formula :CTR = clicks/paidImpressions *100

ecpm 

numeric

Average CPM (cost per thousand) for the impressions.

lostBidsByAuction

numeric

Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  

lostBidsByBlockList

numeric

Number of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s allowlist.

lostBidsByDWLF

numeric

Number of bids lost due to Deal Allowlisted Flag (DWLF).

lostBidsByFloor

numeric

Number of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.  

nonZeroBidReceived

numeric

Number of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually.

paidImpressions 

numeric

Number of impressions won by the demand partner.

spend

numeric

Spend generated by an impression request.

totalLostBidsAdv

numeric

Total number of advertiser bid responses that did not win the impressions. 

totalLostBidsAtd

numeric

Total number of buyer bid responses that did not win the impressions. 

Get the Bulk-Data Details for a DSP

Access bulk-data details for a DSP. 

Request

URI

http://${URI_PREFIX}/v1/analytics/data/dsp/{dspId}

HTTP Method

GET

Request Headers

Header Name

Type

Value

Required

Description

Authorization

String 

Bearer

${access_token}

YES 

The access token generated for authentication should be sent in place of ${access_token}. Example:

curl "http://api.pubmatic.com/v1/analytics/data/dsp/xxxxx?dateUnit=date&dimensions=siteId&filters=&fromDate=2015-01-01T00:00&metrics=spend,paidImpressions,ecpm&pageSize=10&sort=-spend&toDate=2015-01-31T23:59" -H "Authorization: Bearer BDxxxx9d"

Request Path Parameters

Name

Type

Required

Validations

Description

dspId

Integer

YES

DSPs can query only their own data.

Indicates the DSP ID.

Request Query Parameters                                                                           

Excerpt Include
EX:API Data Pull - Request Query Parameters Excerpt
EX:API Data Pull - Request Query Parameters Excerpt
nopaneltrue

Response

Header Name

Type

Description

Content-Type

application/json

JSON response

Response Body

Excerpt Include
EX:API Data Pull - Response Body Parameters Excerpt
EX:API Data Pull - Response Body Parameters Excerpt
nopaneltrue

HTTP Status Codes

The table below lists common HTTP status codes sent in REST API responses from the PubMatic API platform.

Status

Description

Type

Description

400

Bad Request

client-side error

There is some validation failure; check the response body for error details.

401

Unauthorized


There is an authentication or authorization failure; check the response body for specific details.

403

Forbidden


You are not subscribed to this feature of the Platform.

404

Not Found


The server does not have this resource.

503



Service Not Available or too many requests.

500

Internal Server Error

API-side error

There is problem in the PubMatic API Platform. Please contact the PubMatic API support team.

Available Dimensions

Dimensions are attributes, such as CountryPlatform, and Site, available in the PubMatic system. The following tables provide information about dimension grouping.

Dimensions for Historic Data

Dimension ID

Data Type

Description

adFormatId

numeric

Type of ad associated with the impression (example: video, display).

adSizeId 

numeric

Size of ad associated with the impression (example: 200x800).

advertiserCategoryId 

numeric

Indicates category of advertiser.

advertiserId

numeric

Name of the advertiser associated with the ad. Advertisers spending on "Reseller" will appear as "Reseller - Advertiser".

atdId

numeric

Name of the ATD, agency, or buyer associated with the DSP that won the impression

campaignId

numeric

Campaign of the advertiser associated with the ad.

categoryId

numeric

Category of the site from which an impression was requested.

channelId

numeric

Sales channel through which the impression was won (example: PMP, RTB).

cookied

numeric

Indicates whether the DSP's cookies were dropped when an impression was requested.

countryId 

numeric

Country from which an impression was requested. (Refer to  How Countries are Reported in Analytics Reports  for more information)

Info

This dimension is not available in hourly view. You must query using date range only. 


dataCenter 

numeric

Data Center

date

numeric

Date (YYYY-MM-DD format) on which an impression was requested. 

dealMetaId

numeric

Name of the Marketplace deal that won the impression.
This is the numeric ID that the PubMatic system uses to track the Deal.

domainId

numeric

Advertiser Domain is the domain name (Web address) of the advertiser. These domains are identified by the landing page of the impression displayed.

foldPositionId

numeric

Fold placement associated with the ad tag used when an impression was requested.

hour

numeric

Time (YYYY-MM-DD'T'HH format) at which an impression was received. 

mobDeviceIdFlag

numeric

Indicates whether the user's device ID is present in the impression requests.

mobDeviceIdTypeId

numeric

Type of device used by the visitor to generate an impression request.

mobDeviceTypeId

numeric

Type of device ID used by the visitor to generate an impression request.

mobGeoSourceFlag

numeric

Source that provided the visitor's geographical location.

mobLatLongFlag

numeric

Indicates whether the visitor's latitude/longitude details were included in the impression request.

month

numeric

Month (YYYY-MM format) at which an impression was received.

multiBids

numeric

Total number of bid responses for a bid request.

platformId

numeric

Platform through which an impression was requested (example: Web, Mobile Web).

pubId

numeric

Publisher associated with the impression requests.

secureStatus

numeric

Indicates whether the inventory is secure.

siteId

numeric

ID of the site from which an impression was requested.

Dimensions for Domain Data

Info
titleThe Domain Report displays…

Only domains for allowlisted publishers and channel partners.

                                 

Dimension ID

Data Type

Description

applicationId

numeric

Mobile App

bundleId

numeric

Mobile Bundle

dspTldId

numeric

Mobile Bundle

Available Metrics

The following tables list available metrics for DSP bulk-data.

Metrics for Historical Data

Metric ID

Data Type

Description

averageBidEcpmAdv 

numeric

Average CPM of the bid responses associated with an advertiser.      

averageBidEcpmAtd

numeric

Average CPM of the bid responses associated with a buyer.        

averageBidEcpmDsp 

numeric

Average CPM of the bid responses received from a DSP.

bidLossRateAdv

numeric

Number of lost bids as % of total bids for Advertiser.

Formula: bidLossRateAdv = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived  

bidLossRateAtd

numeric

Number of lost bids as % of total bids for ATD.

Formula: bidLossRateAtd = (nonZeroBidReceived - paidImpressions ) * 100 / nonZeroBidReceived

bidLossRateDsp

numeric

Number of lost bids as % of total bids for DSP.

Formula : bidLossRateDsp = (nonZeroBidResponses - paidImpressions) * 100 / nonZeroBidResponses

bidPercentageAdv

numeric

Number of non-zero bids received as % of bid received.

Formula: bidPercentageAdv =  (nonZeroBidReceived / totalBidsRequestsAdv ) * 100

bidPercentageAtd

numeric

Number of non-zero bids received as % of bids received.

Formula: bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidPercentageDsp 

numeric

Number of non-zero bids received as % of bids received.

Formula: bidPercentageAtd = ( nonZeroBidReceived / totalBidsRequestsAtd ) * 100

bidRequestCount 

numeric

Bid Request Count

bidWinRateAdv 

numeric

An advertiser's paid impressions divided by non-zero bids received, expressed as a percentage.

Formula : (Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateAtd

numeric

A buyer's paid impressions divided by non-zero bids received, expressed as a percentage.

Formula : (Paid Impressions * 100) / Non-Zero Bids Received

bidWinRateDsp

numeric

A DSP's paid impressions divided by non-zero bid responses, expressed as a percentage.

Formula :(Paid Impressions * 100) / Non-Zero Bid Responses

clicks

numeric

Number of paid impressions clicked by users.

ctr

numeric

Effectiveness of an ad based on the number of clicks it receives compared to the number of times it is displayed.

Formula :CTR = clicks/paidImpressions *100

ecpm

numeric

Average CPM (cost per thousand) for the impressions.

lostBidsAmountByCBLK

numeric

Lost Bid Amount by Creative Block.

lostBidsByAuction

numeric

Number of bid responses that did not win the impression (lost to other bid responses from DSPs and ad networks).  

lostBidsByBlockList

numeric

Number of bid responses that did not win the impression because the attributes were either included in the publisher\u2019s blocklist or not included in the publisher\u2019s allowlist.

lostBidsByCBLK 

numeric

Lost Bid Count by Creative Block.

lostBidsByDWLF

numeric

Number of bid responses that did not win the impression because the associated Marketplace deal's allowlist did not include the advertiser associated with the bid.

lostBidsByFloor

numeric

Number of bid responses that did not win the impression because the demand partner's bid value was below the floor set in the Marketplace Rule Manager.

nonZeroBidReceived  

numeric

Number of bids in responses from demand partners that had a non-zero bid value. In case of multi-bid responses, each non-zero bid in the response is counted individually. 

nonZeroBidResponses

numeric

Number of bid responses from demand partners that had a non-zero bid value; indicates bid responses intended to participate in the auction.  

paidImpressions

numeric

Number of impressions won by the demand partner.  

queryPerSecond 

numeric

Queries Per Second

spend 

numeric

Spend generated by an impression request.

timeoutRate

numeric

Rate at which the ad timed out or failed to load.

Formula: (Number of timeouts / Total number of requests to the DSP) * 100    

totalBidResponses  

numeric

Total bid responses received by the PubMatic system. 

totalBidsRequestsDsp

numeric

Total number of bid requests sent by PubMatic to a DSP.    

totalLostBidsAdv 

numeric

Total number of advertiser bid responses that did not win the impressions.

totalLostBidsAtd

numeric

Total number of buyer bid responses that did not win the impressions.

totalLostBidsDsp

numeric

Total number of DSP bid responses that did not win the impressions.  

totalRequests

numeric

Total Requests

vctr

numeric

Click Through Rate

video25PercentCount

numeric

25% Video Count

video50PercentCount

numeric

50% Video Count

video75PercentCount

numeric

75% Video Count

videoClicksCount

numeric

Video Click Count

videoCompleteCount

numeric

Video Complete Count  

vtr

numeric

Video Through Rate


Excerpt Include
ex:API Data Pull - OpenWrap Analytics Excerpt
ex:API Data Pull - OpenWrap Analytics Excerpt
nopaneltrue

Page Turner