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.

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 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”.

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

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>



}

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

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"
}'