Analytics Custom Key-Value Pair Reporting

Document created by catherine.racette on Mar 15, 2018Last modified by Anuja.Chockalingam on Jun 5, 2018
Version 7Show Document
  • View in full screen mode


This process enables publishers to pass custom key-value pairs in ad calls to the ad server and is supported for PubMatic API customers.

  • Publishers using the PubMatic AdServer API can pass key-value pairs in the dctr parameter. Refer to HTTP Parameters Details (SSP Ad Server) for more information.
  • Publishers using the OpenRTB 2.3 integration can pass key-value pairs in the App or Site extension objects. 
    • Web traffic (desktop or mobile): pass key-value pairs through Site.ext. Refer to Object: Site.ext for more information.
    • In-app traffic: pass key-value pairs through App.ext. Refer to Object: App.ext for more information.


Data Pull Flow

Before using PubMatic APIs, first generate the API Token. For more information, refer to Getting Started with PubMatic APIs


Webhook Registration

Once you have your access token, a one-time setup is required before data pull requests can be submitted. If this step is skipped, PubMatic will send an email notification of data availability reports to the user associated with the pubtoken instead of the endpoint.


If a change is required in the endpoint, this step can be repeated with a different endpoint URL, as explained below.

Note: {id}= the publisher ID in PubMatic.

DescriptionMethod PathHTTP Method TypeBody Content
Add a new endpoint to the list of existing endpoints




Where, url = A new endpoint where PubMatic will send the notification for data availability in addition to the original list.

Remove given endpoint from the list/v1/analytics/ptp/publisher/notification/update/{id}DELETE



Where, url = Remove given endpoint from a list of existing endpoints.

Note: If empty string is passed, PubMatic will not do anything.   



Data Pull Flow

1. Submit data pull requests or schedule reports

The publisher submits data pull requests with GET method to the endpoint provided by PubMatic. Alternatively, the publisher can schedule reports for a specific frequency.

DescriptionMethod Path
HTTP Method Type
Request Query Parameters
Expected Response
Submit data pull requests to PubMatic/v1/analytics/ptp/publisher/{id}GET

dateUnit=Supported time units. Example: date


dimensions=list of supported dimensions separated by comma. Example: siteId,countryId,date,keyValue


metrics=list of supported metrics separated by comma. Example: revenue,paidImpressions,totalRequests


fromDate=Start date of data retrieval. Example: 2018-01-01


toDate=End date of data retrieval. Example: 2018-01-02



Note: Publisher must store above "queryId" to pull data for this request and to check the status of the data availability/report status. If dateUnit, dimensions, metrics or date ranges are not supported or invalid, PubMatic will return error.



2. Obtain the status of the request

Get the status of whether the report query was submitted successfully or whether to abort the data pull request.

DescriptionMethod Path
HTTP Method Type
Request Query Parameters
Expected Response
Status of the report query is successful/v1/analytics/ptp/publisher/status/{id}GET

queryId=Returned query id in step 1. Example: 1234abc

{"queryId":"1234abc", "status":"COMPLETED"}


Possible statuses:

COMPLETED: Data is available to be pulled.

JOB_SUCCEEDED: Job completed the data pull.

JOB_RUNNING: Job to prepare data is running.

FAILED: Data pull failed.

ABORTED: Data pull request aborted.

Abort the data pull request



queryId=Returned query id from step 1.

Example: 1234abc

200 ok


3. PubMatic sends metadata for the data pull in a webhook notification

Once data is available to be pulled, PubMatic sends a webhook notification; a simple HTTP POST notification to the endpoint provided by the publisher.

HTTP Method Type
Expected Response
POST notification with downloadURL to download data from PubMaticPOST



Where, “downloadURL”= The endpoint from where data in .csv template can be downloaded. Endpoint is present only if status = “COMPLETED”, otherwise it will be empty.


Possible statuses:

COMPLETED: Data is available to be pulled.

FAILED: Data pull failed. In this case, there will be an errorCode and an errorMessage as part of the response. Depending upon the error code, we recommend appropriate actions or check with your CSOM/TE. 

Note: If PubMatic does not receive “200 OK”, then PubMatic will retry to send the notification.                  



4. Download data

The publisher can connect to the endpoint shared by PubMatic to download the data in CSV format.

DescriptionMethod PathHTTP Method Type
Download data from PubMatic





Note: PubMatic will store data for a maximum of 90 days after initial request submission for given queryId.


Supported Dimensions and Metrics


Dimension TypeDescription
siteIdnumericURL of the site from which an impression was requested.
adTagIdnumericName of the ad tag used when an impression was requested.
datestringDate (YYY-MM-DD format) on which an impression was requested.
countryIdnumericCountry from which an impression was requested.
keyValuestringKey-value string passed in the extension object for OpenRTB or "dctr" field of the SSP Ad Server API



paidImpressionsnumericNumber of impressions won by the demand partner.
revenuenumericRevenue amount generated by the winning impressions.
totalRequestsnumericTotal requests.
clicksnumericNumber of paid impressions clicked by users.


Character Support 

Characters ("," ":" "{" "}" "[" "]") must be avoided from the key-value pairs.


String Length Limitations

StringMaximum Length
Key Length16 characters
Value Length256 characters
Key-Value Pairs Input Request50 pairs
Values per Key10 values
Input Request Key-Value Parameter Size (Size of dctr parameter)512 characters