The /reports
endpoint is the primary endpoint for reporting requests. In order to provide maximum flexibility, many configuration options are available for requests.
While the Adobe Analytics UI can help an analyst or digital marketer answer key questions, the Analytics API can automate those answers by reporting to executive dashboards, custom reporting platforms, or tight Experience Cloud integrations. Because the /reports
endpoint uses the same API as the Analytics UI, you can configure it for many options.
Before you can use Analytics APIs, you need to obtain authentication and receive authorization. For more information, see the Getting Started guide.
The /reports
endpoint description is shown in our Swagger UI. Use the Swagger UI to see endpoint summaries, available methods, parameters, example values, models, and status codes, and to try out the API.
A 206 status code indicates a partial response. This means there were some columns in the reporting response that have errors. These errors may be any of the following:
- Unauthorized Metric: User does not have access to the requested metric
- Metric Not Enabled: The requested metric is not enabled in this report suite
- Unauthorized Dimension: User does not have access to the requested dimension
- Dimension Not Enabled: The requested dimension is not enabled in this report suite
- Unauthorized Global Dimension: User does not have access to the global dimension for this request
- Global Dimension Not Enabled: The global dimension for this request is not enabled in this report suite
- Unexpected Number of Items: Anomaly Detection algorithm returned an unexpected number of anomalies
- General Service Error: General Anomaly Detection service error
Please follow these guidelines when using Analytics APIs:
- Make multiple, smaller requests instead of a large, single request.
- Request data once and cache it.
- Do not poll for new data faster than a 30 minute interval.
- Pull historical data and increment it regularly instead of requesting the entire data set.
Discouraged Practices:
- Requesting as much data as possible in a single request
- Requesting one year of data at day granularity everyday - just request the new day and merge it
- Driving a web page with a site performance widget by making an API request every time the web page is loaded
- Requesting a full year of day-level data every day to get a rolling 12-month window
The Reports API includes Time Series reports. These simple reports include information about the performance of a metric (or metrics) over a period of time.
The following request example includes both a JSON message request body and a curl
request for the Page Views metric.
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
],
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
]
},
"dimension":"variables/daterangeday",
"settings":{
"dimensionSort":"asc"
}
}
The JSON message requests the following:
-
Page Views metric for the report suite
adbedocrsid
(lines 12 and 2) -
Time period From Dec. 31, 2017 00:00:00.000 - Jan. 06, 2018 23:59:59.999, using the report suite timezone (line 22)
-
variables/daterangeday
granularity (line 26). With seven days specified in this time period, you can expect seven numbers in the response. -
Sort response by ascending date, i.e. oldest to newest (line 28)
curl -X POST \
https://analytics.adobe.io/api/{COMPANYID}/reports \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {ACCESSTOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {APIKEY}' \
-H 'x-proxy-global-company-id: {COMPANYID}' \
-d '{REQUESTJSON}'
{
"totalPages":1,
"firstPage":true,
"lastPage":false,
"numberOfElements":7,
"number":0,
"totalElements":7,
"columns":{
"dimension":{
"id":"variables/daterangeday",
"type":"time"
},
"columnIds":[
"0"
]
},
"rows":[
{
"itemId":"1171131",
"value":"Dec 31, 2017",
"data":[
794.0
]
},
{
"itemId":"1180001",
"value":"Jan 1, 2018",
"data":[
16558.0
]
},
{
"itemId":"1180002",
"value":"Jan 2, 2018",
"data":[
17381.0
]
},
{
"itemId":"1180003",
"value":"Jan 3, 2018",
"data":[
17384.0
]
},
{
"itemId":"1180004",
"value":"Jan 4, 2018",
"data":[
17442.0
]
},
{
"itemId":"1180005",
"value":"Jan 5, 2018",
"data":[
17417.0
]
},
{
"itemId":"1180006",
"value":"Jan 6, 2018",
"data":[
17334.0
]
}
],
"summaryData":{
"totals":[
104310.0
]
}
}
The JSON response includes the following information:
-
The
rows
section contains each report record. In the above example, you can see seven rows, each with avalue
anddata
array (lines 19-66). -
The
value
property contains the dimension value. Because the request includes a total of page views by day, the value of each row will contain a date identifier for the day (e.g. line 25). For time series data, this identifier changes based on the granularity. For example, if you requestvariables/daterangemonth
instead, each value will contain a month/year identifier. -
The
data
property contains a list of metric counts for each metric requested. Since only one metric is requested, only a single total appears in each row (e.g. lines 26-28). -
The
summaryData
section contains a total of the metrics in the current report (lines 72-74).
You can also easily modify this example to get metrics for visits. Simply change the id
property in the metrics
section to metrics/visits
(line 15).
To paginate results, add a limit
and page
parameter to the settings
object (lines 29-30 below):
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-31T23:59:59.999"
}
],
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-31T23:59:59.999"
}
]
},
"dimension":"variables/daterangeday",
"settings":{
"dimensionSort":"asc",
"limit":"10",
"page":"2"
}
}
Default limit is 50, max of 50000.
The Reports API can also identify anomalies in a metric over a given time period. This can be helpful in setting up automated alert tools or dashboards to report the same information as the UI. When using this feature, anomalies are reported for values outside the upper or lower bound of the confidence bands. The building model and confidence bands are pre-defined in Analytics by calculated historical norms. Although this ability is also available with the Anayltics 1.4 APIs, the Analytics 2.0 APIs now include hour-based granularity.
The following request includes an additional parameter to the settings
object to turn on anomaly detection (line 29).
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
],
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
]
},
"dimension":"variables/daterangeday",
"settings":{
"dimensionSort":"asc",
"includeAnomalyDetection":true
}
}
This example response shows an anomaly condition and identifies the following five properties with their corresponding values:
data
- The actual detected value for the metric (lines 21 and 40)dataExpected
- The calculated expected value for the metric (lines 23 and 42)dataUpperBound
- The upper limit of the confidence band (lines 26 and 45)dataLowerBound
- The lower limit of the confidence band (lines 29 and 48)dataAnomalyDetected
- An indicator of whether the metric value is outside of the confidence bands, i.e.True
if detected (lines 33-34 and 52-53).
{
"totalPages":1,
"firstPage":true,
"lastPage":false,
"numberOfElements":7,
"number":0,
"totalElements":7,
"columns":{
"dimension":{
"id":"variables/daterangeday",
"type":"time"
},
"columnIds":[
"0"
]
},
"rows":[
{
"itemId":"1171131",
"value":"Dec 31, 2017",
"data":[
794.0
],
"dataExpected":[
17395.648628666
],
"dataUpperBound":[
17462.569820465
],
"dataLowerBound":[
17328.727436868
],
"dataAnomalyDetected":[
true
]
},
...SNIP...
],
"summaryData":{
"totals":[
104310.0
]
}
}
In Analytics, simple time series reports have metrics. If you add a dimension, you can request Ranked reports. For example, some of the previous examples above include a date for the dimension so they can be considered Ranked reports. If you also include a time range with a metric and a dimension, you can request Trended reports. For more information on report types in Analytics, see Adobe Report Types help. In the following examples, a Custom Insight Conversion Variable (evar1) is used as the dimension for the report.
In the following request, evar1
is simply storing a numeric ID for a campaign (see line 26).
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
],
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
]
},
"dimension":"variables/evar1",
"settings":{
"dimensionSort":"asc",
"limit":5
}
}
In the following response, each record returns:
itemId
- This is the unique ID associated with this particular value - in this case, campaign "10".value
- This contains the value of the evar.data
- This is an array of counts - one for each metric requested.
{
"totalPages":8,
"firstPage":true,
"lastPage":false,
"numberOfElements":5,
"number":0,
"totalElements":40,
"columns":{
"dimension":{
"id":"variables/evar1",
"type":"string"
},
"columnIds":[
"0"
]
},
"rows":[
{
"itemId":"0",
"value":"Unspecified",
"data":[
11560.0
]
},
{
"itemId":"219343969",
"value":"15",
"data":[
524.0
]
},
{
"itemId":"349230650",
"value":"7",
"data":[
4420.0
]
},
{
"itemId":"511036305",
"value":"11",
"data":[
1631.0
]
},
{
"itemId":"743855946",
"value":"10",
"data":[
2032.0
]
}
],
"summaryData":{
"totals":[
104310.0
]
}
}
Media concurrent viewers report is a time series report with two specialized metrics.
metrics/concurrent_viewers_visitors
It counts number of unique visitors.metrics/concurrent_viewers_occurrences
It counts number of active sessions.
These metrics can be rolled up to different granularity based on the dimension. For example unique visitors per minute or unique visitors per day etc. These are different dimensions available for media concurrent viewers report.
variables/daterangeminute
variables/daterangehour
variables/daterangeday
variables/daterangeweek
variables/daterangemonth
variables/daterangequarter
variables/daterangeyear
Media concurrent viewers report can be used in conjunction with filtering capabilities explained in Filtering Reports section.
The following request example includes both a JSON message request body to request number of unique visitors.
{
"rsid": "adbedocrsid",
"locale": "en_US",
"dimension": "variables/daterangeminute",
"globalFilters": [
{
"dateRange": "2019-08-01T00:00/2019-08-01T00:05",
"type": "dateRange"
}
],
"metricContainer": {
"metrics": [
{
"columnId": "column1",
"id": "metrics/concurrent_viewers_visitors"
}
]
},
"settings": {
"dimensionSort": "asc",
"limit": "100",
"page": 0
}
}
The JSON message requests the following:
-
Number of unique visitors metric
metrics/concurrent_viewers_visitors
(line 15) for the report suiteadbedocrsid
(line 2) -
Time period From Aug. 01, 2019 00:00:00.000 - Aug. 01, 2018 01:00:00.000, using the report suite timezone (line 7)
-
variables/daterangeminute
granularity (line 4). With five minutes specified in this time period, you can expect five rows in the response. -
Sort response by ascending date, i.e. oldest to newest (line 20)
In the following response, each record returns:
itemId
- This is the unique ID associated with this particular value - in this case, unique visitors on Aug. 01, 2019 00:01 AM (line 27).value
- This contains the value of the dimension Aug. 01, 2019 00:01 AM.data
- This is an array of counts - one for each metric requested - in this case number of unique visitors.
{
"totalPages": 1,
"firstPage": true,
"lastPage": true,
"numberOfElements": 5,
"number": 0,
"totalElements": 5,
"columns": {
"dimension": {
"id": "variables/daterangeminute",
"type": "time"
},
"columnIds": [
"column1"
]
},
"rows": [
{
"itemId": "11907010000",
"value": "00:00 2019-08-01",
"data": [
326.0
]
},
{
"itemId": "11907010001",
"value": "00:01 2019-08-01",
"data": [
258.0
]
},
{
"itemId": "11907010002",
"value": "00:02 2019-08-01",
"data": [
202.0
]
},
{
"itemId": "11907010003",
"value": "00:03 2019-08-01",
"data": [
148.0
]
},
{
"itemId": "11907010004",
"value": "00:04 2019-08-01",
"data": [
79.0
]
}
],
"summaryData": {
"filteredTotals": [
1285.0
],
"totals": [
22346.0
]
}
}
Use filters to limit the data returned so that reports show only the values you need. For example, if you have thousands of records but only a few have needed reports, you can use filtering to return and find them quickly. Some filters also allow you to include, group, or present data in convenient formats, such as breakdown reports.
This section includes information on the following filtering features:
-
Search parameter
-
Clause parameter
-
Applying Segments
-
Breakdown Reports
By using the search
parameter, you can add even more granular parameters to filter your results more narrowly. The search
parameter includes the following options:
itemIds
- A list of itemIds to include in the report (shown in the example)excludeItemIds
- A list of itemIds to exclude in the reportclause
- A search clause to use when filtering dimensions
The following example requests data only for campaigns "10" and "11" with the search
parameter by using their itemIds (line 9).
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
],
"search":{
"itemIds":[743855946,511036305]
},
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
]
},
"dimension":"variables/evar1",
"settings":{
"dimensionSort":"asc",
"limit":5
}
}
The following response returns the data requested for the itemId
associated with campaigns 10 and 11 (lines 18-21 and 25-28).
{
"totalPages":1,
"firstPage":true,
"lastPage":true,
"numberOfElements":2,
"number":0,
"totalElements":2,
"columns":{
"dimension":{
"id":"variables/evar1",
"type":"string"
},
"columnIds":[
"0"
]
},
"rows":[
{
"itemId":"511036305",
"value":"11",
"data":[
1631.0
]
},
{
"itemId":"743855946",
"value":"10",
"data":[
2032.0
]
}
],
"summaryData":{
"totals":[
104310.0
]
}
}
As noted above, the search
parameter also includes the clause
option. The clause
parameter provides a powerful tool for filtering data. To use it, follow these rules:
- It uses boolean operators
AND
,OR
, andNOT
. - It uses operators
MATCH
,CONTAINS
,BEGINS-WITH
, andENDS-WITH
. - It uses group conditions with parenthesis.
- Strings are contained in single quotes.
- Searches are case-insensitive.
- If no operator is specified, a 'contains' match is performed.
- Valid operators are 'match' and 'contains'.
- Glob expressions are evaluated. If a literal
*
is needed, use\*
.
- Only include results that match the string 'home page':
MATCH 'home page'
- Include pages that do not contain 'home page':
NOT CONTAINS 'home page'
- Include pages that do not contain 'home page' or 'about us', but do contain 'contact us':
(NOT CONTAINS 'home page' OR NOT CONTAINS 'about us') AND (CONTAINS 'contact us')
- Include pages that contain 'home page' or start with 'landing':
CONTAINS 'home page' OR BEGINS-WITH 'landing'
You can include a segment in your report by adding it to the globalFilters
property.
The following example shows a segment requested as part of the globalFilters
property:
...
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2014-06-01T00:00/2014-06-21T00:00"
},
{
"type":"segment",
"segmentId":"53adb46be4b0a2a175bf38c4"
}
],
...
Breakdowns in the API are useful when you want to see the cross-product of values from two different dimensions. When requesting a breakdown report, use the metricsFilters
and dimension
parameters to request the additional dimension.
The following example requests a breakdown report containing a list of the top five "Internal Search Terms" used by visitors who saw campaign 10. Within the metricsFilters
parameter, the type is set to breakdown
(line 21), and evar1
is the marketing campaign (line 22). Within the dimensions
parameter, evar2
is the "Internal Search Terms" (line 27).
Note: If the text value of item is already known, it can be passed inside the metricFilter
object as itemValue
field (Make sure to pass the exact text value).
For example, instead of passing the item id "itemId":"743855946"
of the item "Campaign 10", we can pass the text value of the item like this "itemValue" : "10"
Passing an item value instead of item id will result in slightly slower performance, but it will be useful in preventing multiple reporting calls to retrieve item ids.
{
"rsid":"adbedocrsid",
"globalFilters":[
{
"type":"dateRange",
"dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999"
}
],
"metricContainer":{
"metrics":[
{
"columnId":"0",
"id":"metrics/pageviews",
"filters":[
"0"
]
}
],
"metricFilters":[
{
"id":"0",
"type":"breakdown",
"dimension":"evar1",
"itemId":"743855946"
}
]
},
"dimension":"variables/evar2",
"settings":{
"dimensionSort":"asc",
"limit":5
}
}
The following example shows that the top search terms for Campaign 10 are "red t-shirt", "digital watches", "sport socks", "gps watch", and "running shoes."
{
"totalPages":2,
"firstPage":true,
"lastPage":false,
"numberOfElements":5,
"number":0,
"totalElements":7,
"columns":{
"dimension":{
"id":"variables/evar2",
"type":"string"
},
"columnIds":[
"0"
]
},
"rows":[
{
"itemId":"1132341824",
"value":"red t-shirt",
"data":[
1515.0
]
},
{
"itemId":"2400044733",
"value":"digital watches",
"data":[
1.0
]
},
{
"itemId":"3351316813",
"value":"sport socks",
"data":[
11.0
]
},
{
"itemId":"3440395251",
"value":"gps watch",
"data":[
95.0
]
},
{
"itemId":"3614317595",
"value":"running shoes",
"data":[
16.0
]
}
],
"summaryData":{
"totals":[
2032.0
]
}
}
For a more in-depth example of breakdowns see the following guide: Reporting with Multiple Breakdowns
TopItems in the API are useful when you want to see the top X items for the specified dimension and RSID.
The following example shows the top items report response for the dimension "variables/page"
{
"totalPages": 13,
"firstPage": true,
"lastPage": false,
"numberOfElements": 10,
"number": 0,
"totalElements": 124,
"reportId": "topItems",
"rows": [
{
"itemId": "4171620885",
"value": "Other"
},
{
"itemId": "631347493",
"value": "Shopping Cart|Cart Details"
},
{
"itemId": "2804340665",
"value": "Home"
},
{
"itemId": "2981341139",
"value": "Search Results"
},
{
"itemId": "2700590175",
"value": "Store Locator|Search"
},
{
"itemId": "3783105718",
"value": "Shopping Cart|Shipping Information"
},
{
"itemId": "3916049137",
"value": "Equipment"
},
{
"itemId": "3189330925",
"value": "Shopping Cart|Billing Information"
},
{
"itemId": "3694966131",
"value": "Store Locator|Results"
},
{
"itemId": "925217727",
"value": "Product List"
}
]
}