Aggregated Data Reports

Operations to fetch aggregated reporting data

Aggregated data reports endpoints are the most powerful reports in the Everflow platform. They power many different reports in the UI and allow you to pull reporting metrics by pivoting your data based on one or multiple columns. Concretely, the report will allow you to, for example, pull all reporting metrics per offer, effectively turning each offer into a reporting “line”.

Using multiple columns like "offer" and "country" would mean that each reporting “line” is a unique couple of offer / country.

The endpoints documented here all support the same columns and can take up to 10 columns in a single request. At least one column must be specified in each request.

Requested intervals are limited to a maximum duration of one year. For example, requests with "from": "2022-01-01", "to": "2023-12-31" are considered invalid and will return an error.

View Columns

Note that you can only use a single time-related column at a time. For example, using both week and hour at the same time won’t work.

Column	Description
offer	Group by offer id
creative	Group by creative id
coupon_code	Group by coupon code
offer_url	Group by offer url
country	Group by country
country_code	Group by country code
region	Group by region
city	Group by city
dma	Group by dma
carrier	Group by carrier
platform	Group by platform
isp	Group by isp
os_version	Group by OS version
device_type	Group by device type
device_model	Group by device model
device_make	Group by device make
browser	Group by browser
language	Group by language
sub1	Group by sub1 (same for sub2-5)
source_id	Group by source id
referer	Group by referer
event_name	Group by event name
connection_type	Group by connection type
tracking_domain	Group by tracking domain
hour	Group by hour
date	Group by date
week	Group by week
month	Group by month
year	Group by year

Table

POST /v1/affiliates/reporting/entity/table

The main endpoint on which you can pivot your data. Each request must contain :

from and to dates
timezone_id used for the request. Find all timezones here
currency_id used for the reporting metrics
At least one column

Optional query filters can then be added to the call.

Please note that the endpoint is limited to 10,000 rows. If you hit the limit, response will include "incomplete_results": true in the payload. When that’s the case, either reduce the number of columns or reduce the scope of the report you are requesting.

Query Filters

Query filters allow you to limit the scope of the report returned by the API. You could create a filter to limit the reporting data to a single partner for example. You can use multiple filters in a request.

Filters that apply to the same resource_type will act as OR operator. Different resource_type work with an AND operator. The following filters :

{
  //...
  "query": {
    "filters": [
      {
          "filter_id_value": "883",
          "resource_type": "offer"
      },
      {
          "filter_id_value": "518",
          "resource_type": "offer"
      },
      {
          "filter_id_value": "United States",
          "resource_type": "country"
      }
    ]
  }
}

translate to “Pull reporting data for US traffic on offer 883 OR offer 518”.

Filter Resource Types

The resource-type used in the filters and exclusions can take the following values :

offer, creative, country, country_code, sub1, sub2, sub3, sub4, sub5, carrier, device_platform, device_type, device_make, browser, language, connection_type, campaign, source_id, offer_url, device_model, os_version, coupon_code

Examples

The following examples are different variations of what you can pass as a payload in the following call :

cURL

curl --request POST 'https://api.eflow.team/v1/affiliates/reporting/entity/table' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--header 'Content-Type: application/json' \
--data '<INSERT PAYLOAD>'

Example 1 : Pull all reporting data for the 8th of February 2022 (from midnight until 23h59:59) broken down by offer

{
    "from": "2022-02-08",
    "to": "2022-02-08",
    "timezone_id": 67,
    "currency_id": "USD",
    "columns": [
        {
            "column": "offer"
        }
    ],
    "query": {
        "filters": [ ]
    }
}

Example 2 : Pull all reporting data for the 8th of February 2022 (from midnight until 23h59:59) for offer IDs 882 and 883

{
    "from": "2022-02-08",
    "to": "2022-02-08",
    "timezone_id": 67,
    "currency_id": "USD",
    "columns": [
        {
            "column": "offer"
        }
    ],
    "query": {
        "filters":
        [
            {
                "filter_id_value": "882",
                "resource_type": "offer"
            },
            {
                "filter_id_value": "883",
                "resource_type": "offer"
            }
        ],
    }
}

Example 3 : Include only traffic that comes from the US or Canada and that has the "internal" value passed as a sub1. Break the data down by device type

{
    "from": "2022-02-01",
    "to": "2022-02-07",
    "timezone_id": 90,
    "currency_id": "USD",
    "columns":
    [
        {
            "column": "device_type"
        }
    ],
    "query":
    {
        "filters":
        [
            {
                "filter_id_value": "internal",
                "resource_type": "sub1"
            },
            {
                "filter_id_value": "Canada",
                "resource_type": "country"
            },
            {
                "filter_id_value": "United States",
                "resource_type": "country"
            }
        ]
    }
}

Example 4 : Reporting metrics for all smart links currently running, broken down per smart link / destination offer :

{
    "from": "2022-02-01",
    "to": "2022-02-01",
    "timezone_id": 80,
    "currency_id": "USD",
    "columns":
    [
        {
            "column": "campaign"
        },
        {
            "column": "offer"
        }
    ],
    "query":
    {
<span style="color:#000;font-weight:bold">}</span>

}

Response

The response from this endpoint varies depending on the columns you requested. The structure will always be the same though, and the reporting metrics included in the response do not vary either.

Given the following request payload :

{
    "from": "2022-02-08",
    "to": "2022-02-08",
    "timezone_id": 67,
    "currency_id": "USD",
    "columns": [
        {
            "column": "offer"
        },
        {
            "column": "country"
        }
    ]
}

The response would look like :

{
	"table": [
		{
			"columns": [
				{
					"column_type": "offer",
					"id": "3",
					"label": "Example Offer Name"
				},
				{
					"column_type": "country",
					"id": "United States",
					"label": "United States"
				}
			],
			"reporting": {
				"imp": 0,
				"total_click": 27,
				"unique_click": 27,
				"invalid_click": 0,
				"duplicate_click": 0,
				"ctr": 0,
				"cv": 2,
				"view_through_cv": 0,
				"event": 0,
				"cvr": 7.407,
				"evr": 0,
				"rpc": 0.059,
				"rpm": 0,
				"revenue": 1.6,
				"redirect_traffic_revenue": 0
			}
		},
		{
			"columns": [
				{
					"column_type": "offer",
					"id": "3",
					"label": "Example Offer"
				},
				{
					"column_type": "country",
					"id": "Canada",
					"label": "Canada"
				}
			],
			"reporting": {
				"imp": 0,
				"total_click": 10,
				"unique_click": 10,
				"invalid_click": 0,
				"duplicate_click": 0,
				"ctr": 0,
				"cv": 2,
				"view_through_cv": 0,
				"event": 0,
				"cvr": 20,
				"evr": 0,
				"rpc": 0.16,
				"rpm": 0,
				"revenue": 1.6,
				"redirect_traffic_revenue": 0
			}
		}
	]
}

Table Export

POST /v1/affiliates/reporting/entity/table/export

The table export is basically identical to the table endpoint documented above, except that it lets you “export” the data in CSV or JSON format.

Please note that when using the JSON format, the results will be newlined delimited JSON.

You must add the format properly to the payloads from the regular table endpoint for requests to work on this endpoint. The format can be either :

csv
json

Example

curl --request POST 'https://api.eflow.team/v1/affiliates/reporting/entity/table/export' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "from": "2022-02-08",
    "to": "2022-02-08",
    "timezone_id": 67,
    "currency_id": "USD",
    "columns": [
        {
            "column": "offer"
        },
        {
            "column": "country"
        }
    ],
    "query": {
        "filters": [ ]
    },
    "format": "csv"
}'