Reporting and Listing API Request Details

PubMatic API platform uses a  consistent format for query parameters to the Reporting and Listing APIs. Each query requires a start and end date. You can also supply additional query parameters with reporting and listing requests such as, dimensions, metrics, filters, and sort, to refine your query. Respective resource endpoints such as /deals, /flights, /insertionOrders, and so on, serve listing requests.

Query Parameters Summary

The following table summarizes the all the query parameters accepted by the Core reporting API. 

NameData TypeRequiredSummary
fromDateString

Yes for Reporting

No for Listing using a resource.

Indicates the start date for fetching reporting data. Requests can specify a start date formatted as YYYY-MM-DD.
toDateString

Yes for Reporting

No for Listing using a resource.

Indicates the end date for fetching reporting data. Requests can specify a start date formatted as YYYY-MM-DD.

metricsStringNoIndicates a list of comma-separated metrics, such as impressionCount,zeroBidRequests.If not provided all metric will available in response
dimensionsStringNoIndicates a list of comma-separated dimensions for your response data, such as pubId,siteId,campaginName.
sortStringNoIndicates a list of comma-separated dimensions and metrics indicating the sorting order and sorting direction for the returned data.
filtersStringNoIndicates the dimension or metric filters that restrict the data returned for your request.
pageNumberIntegerNoIndicates that you can use this parameter as a pagination.
pageSizeIntegerNoIndicates the maximum number of rows to include in the response.

fromDate

Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD; for example, fromDate=2014-01-01.

toDate

Required for all reporting data requests must specify a date range. If you do not include fromDate and toDate parameters in the request, the server returns an error. Date values should be for a specific date by using the pattern YYYY-MM-DD; for example, XA toDate=2014-01-31.

Dimensions

Optional.The dimensions parameter breaks down metrics by common criteria; for example, by siteId or  campaginId  While you can ask for the total number of impressions to your site, it might be more interesting to ask for the number of impressions broken down by site. In this case, you'll see the number of impressions from all sites; for example, dimensions=sitId,campaginId. See Reporting Glossary for a list of available dimensions.

Metrics

Optional. The aggregated statistics of various entities such as impressionCount, bid requests etc. If a query has no dimensions parameter, the returned metrics provide aggregate values for the requested date range. However, when dimensions are requested, values are grouped  by dimension value. For example impressionCount requested with siteId returns the total impressionCount per site. If a query has no metrics then all metrics will be available in response; for example, metrics=impressionCount,zeroBid. See Reporting Glossary for a list of available metrics.

Sort

Optional. A list of metrics and dimensions indicating the sorting order and sorting direction for the returned data.
Sorting direction defaults to ascending but you can change it to descending using a minus sign (-) prefix for a requested field.
Sorting the results of a query enables you to ask different questions about your data. For example, to address the question "What are my top sites, and which impressionsCount do they provide most with less zero bids?" you can make a query with the the following parameter: sort=-impressionCount,zeroBid.

Filters

Optional. The filters query string parameter restricts the data returned from your request. To use the filters parameter, supply a dimension or metric on which to filter, followed by the filter expression. For example, the following query requests impressionCount greater than 10000 served by campaign name starts with the string xyz or ends with abc.

&filters=impressionCount gt 10000&filters=campaignName like xyz*, campaignName like *abc

Searchable Fields

Name

Data Type

Required

Summary

Sample Filter Data

Sample Sort Data

loggedInOwnerId

Long

Yes

A valid Publisher IDDSP ID, or Buyer ID

&filters=loggedInOwnerId eq 12345


loggedInOwnerTypeId

Integer

Yes

One of the following integer values that indicates the account type of the issuing the request:

Type of Account

Value

Publisher

1

buyers

5

ATD/Buyer

7

&filters=loggedInOwnerTypeId eq 1


id

Long

No

SEARCH and SORT is supported.

Plain SEARCH is depreciated as we have a separate endpoint for it.

?filters=id gtEq 298&filters=id lt 301

For ascending order, use ?sort=id

For descending order, use ?
sort=--id

name

String

No

SEARCH and SORT is allowed in this field. 

?filters=name like test

When name search is used, we also search for dealId.

For ascending order, use ?sort=name

For descending order, use ?sort=-name

additionalInfo

String

No

Search deal by its message component.

SORT is depreciated for this field.

?filters=additionalInfo like test


status

Integer

No

SEARCH and SORT is allowed in this field. 

?filters=status eq 1

 For ascending order, use ?sort=status

For descending order, use ?sort=-status

auctionType

Integer

No

SEARCH and SORT is allowed in this field. 

?filters=auctionType eq 1

For ascending order, use ?sort=auctionType

For descending order, use ?
sort=
- auctionType

startDate

Date

No

SEARCH and SORT supported. BETWEEN attribute is not currently supported. But you can use filters like

?filters=startDate gtEq 2014-06-12T17:00:00Z&filters=startDate lt 2014-06-16T17:00:00Z.

?filters=startDate gtEq 2014-06-12T17:00:00Z&filters=startDate lt 2014-06-16T17:00:00Z.

?sort=-startDate

endDate

Date

No

SEARCH and SORT supported.

?filters=endDate gtEq 2014-06-12T17:00:00Z&filters=endDate lt 2014-06-16T17:00:00Z.


flooreCPMIntegerNoSEARCH and SORT supported.?filters=flooreCPM gt 1
channelTypeIntegerNoSEARCH is supported on this field?filters=channelType eq 6
dealCategoryIntegerNoSEARCH is supported on this field?filters=dealCategory eq 1

Sample Calls:

https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=name+like+*PM-CLOM-8057*

https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=channelType+eq+6&filters=status+eq+1

https://api.pubmatic.com/v3/pmp/deals?view=summary&filters=loggedInOwnerId%20eq%2080&filters=loggedInOwnerTypeId%20eq%205&pageSize=2&filters=dealCategory+eq+1

Filter Syntax

A single filter uses the form:

name operator value

In this syntax:

  • name - the name of the dimension or metric to filter on. Example, campaignName filters on the impressionCount metric.
  • operator - defines the type of filter match to use. Operators are specific to either dimensions or metrics.
  • value - states the values to be included in or excluded from the results.In case of String * character supported to find like query and all % character will be ignored.
  • There should be space between name, operator and value.


Note…

  1. Single filters should contain either Dimensions/metric. 
  2. Operators are not cases sensitive for example noteq and NOTEQ are equal.

Filter Operators

OperatorDescriptionSupported Data Types
eqEqualsALL Data Types
notEqNot EqualsALL Data Types
gtGrater ThanNumaric and Date
gtEqGrater Than or EqualsNumaric and Date
ltLess ThanNumaric and Date
lteqLess Than or EqualNumaric and Date
likelikeString
StringStringString