Aggregated Data Reports
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 "affiliate" would mean that each reporting “line” is a unique couple of offer / affiliate.
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 |
| affiliate | Group by affiliate id |
| advertiser | Group by advertiser id |
| offer_group | Group by offer_group id |
| campaign | Group by network campaign id |
| creative | Group by creative id |
| event_name | Group by event id |
| offer_url | Group by offer url id |
| 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 |
| os_version | Group by os version |
| isp | Group by isp |
| browser | Group by browser |
| device_type | Group by device type |
| device_make | Group by device brand (make) |
| model | Group by device model |
| language | Group by language |
| connection_type | Group by connection type |
| sub1 | Group by sub1 value (same for sub2-5) |
| source_id | Group by source id |
| adv1 | Group by adv1 value (same for adv2-5) |
| coupon_code | Group by coupon code |
| tracking_domain | Group by network tracking domain id |
| referer | Group by referer |
| offer_status | Group by offer status |
| affiliate_manager | Group by affiliate manager id |
| account_manager | Group by account manager id |
| category | Group by category id |
| project_id | Group by project id |
| payout_type | Group by payout type |
| payout_amount | Group by payout amount |
| revenue_type | Group by revenue type |
| revenue_amount | Group by revenue amount |
| currency | Group by currency id |
| sales_manager | Group by sales manager id |
| account_executive | Group by account executive id |
| affiliate_status | Group by affiliate status |
| advertiser_event_name | Group by advertiser global event id |
| app_identifier | Group by app identifier |
| bundle_id | Group by bundle id |
Table
/v1/networks/reporting/entity/table
The main endpoint on which you can pivot your data. Each request must contain :
fromandtodatestimezone_idused for the request. Find all timezones herecurrency_idused 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”.
Exclusion Filters
Exclusions are similar to query filters, but instead of forcing you to include many different values they allow you to exclude a single entity. Pulling reporting data for all but a single partner for example :
{
//...
"query": {
"exclusions": [
{
"filter_id_value": "100",
"resource_type": "affiliate"
}
]
}
}
Filter Resource Types
The resource-type used in the filters and exclusions can take the following values :
offer, offer_group, affiliate, advertiser, creative, account_manager, affiliate_manager, category, billing_frequency, country, country_code, carrier, device_platform, device_type, device_make, browser, language, connection_type, campaign, source_id, offer_url, device_model, business_unit, label, sales_manager, account_executive, everflow_account_manager, os_version, project_id, offer_status, sub1, sub2, sub3, sub4, sub5, channel, coupon_code, affiliate_tier
Additional Settings
Aggregated data requests also support 3 entirely optional settings :
ignore_fail_traffic: defaults tofalsewhen omitted – can be used to exclude fail traffic from resultsonly_include_fail_traffic: defaults tofalse– opposite of the setting abovecampaign_data_only: defaults tofalse– the word “campaign” in this context refers to smart links. Turning this on will only return the metrics for traffic that was sent through a smart link.
{
//...
"query": {
"settings": {
"campaign_data_only": false,
"ignore_fail_traffic": false,
"only_include_fail_traffic": false
}
}
}
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/networks/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 and affiliate
{
"from": "2022-02-08",
"to": "2022-02-08",
"timezone_id": 67,
"currency_id": "USD",
"columns": [
{
"column": "offer"
},
{
"column": "affiliate"
}
],
"query": {
"filters": [ ]
}
}
Example 2 : 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 3 : Reporting metrics per affiliate on 2 offers for all but one affiliate
{
"from": "2022-02-01",
"to": "2022-02-02",
"timezone_id": 90,
"currency_id": "USD",
"columns":
[
{
"column": "affiliate"
}
],
"query":
{
"filters":
[
{
"filter_id_value": "882",
"resource_type": "offer"
},
{
"filter_id_value": "883",
"resource_type": "offer"
}
],
"exclusions":
[
{
"filter_id_value": "1",
"resource_type": "affiliate"
}
]
}
}
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":
{
"settings":
{
"campaign_data_only": true,
"ignore_fail_traffic": false
}
}
}
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.
Note that whenever the offer column is requested, the advertiser column is always included in the response on top of the offer column.
The usm_columns and custom_metric_columns will be filled with any user management and custom metrics you created (they are optional).
Given the following request payload :
{
"from": "2022-02-08",
"to": "2022-02-08",
"timezone_id": 67,
"currency_id": "USD",
"columns": [
{
"column": "offer"
},
{
"column": "affiliate"
}
]
}
The response would look like :
{
"table": [
{
"columns": [
{
"column_type": "offer",
"id": "879",
"label": "Example Offer Name"
},
{
"column_type": "advertiser",
"id": "135",
"label": "Example Advertiser Name"
},
{
"column_type": "affiliate",
"id": "20019",
"label": "Partner Inc."
}
],
"reporting": {
"imp": 0,
"total_click": 75,
"unique_click": 75,
"invalid_click": 7027,
"duplicate_click": 0,
"gross_click": 7102,
"ctr": 0,
"cv": 0,
"invalid_cv_scrub": 0,
"view_through_cv": 0,
"total_cv": 0,
"event": 0,
"cvr": 0,
"evr": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"epc": 0,
"rpc": 0,
"rpa": 0,
"rpm": 0,
"payout": 0,
"revenue": 0,
"event_revenue": 0,
"gross_sales": 0,
"profit": 0,
"margin": 0,
"roas": 0,
"avg_sale_value": 0,
"media_buying_cost": 0
}
},
{
"columns": [
{
"column_type": "offer",
"id": "881",
"label": "Other Example Offer"
},
{
"column_type": "advertiser",
"id": "135",
"label": "Example AdvertiserName"
},
{
"column_type": "affiliate",
"id": "20017",
"label": "Other Partner Inc."
}
],
"reporting": {
"imp": 0,
"total_click": 0,
"unique_click": 0,
"invalid_click": 2693,
"duplicate_click": 0,
"gross_click": 2693,
"ctr": 0,
"cv": 0,
"invalid_cv_scrub": 0,
"view_through_cv": 0,
"total_cv": 0,
"event": 0,
"cvr": 0,
"evr": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"epc": 0,
"rpc": 0,
"rpa": 0,
"rpm": 0,
"payout": 0,
"revenue": 0,
"event_revenue": 0,
"gross_sales": 0,
"profit": 0,
"margin": 0,
"roas": 0,
"avg_sale_value": 0,
"media_buying_cost": 0
},
"usm_columns": [],
"custom_metric_columns": []
}
]
}
Table Export
/v1/networks/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 :
csvjson
Example
curl --request POST 'https://api.eflow.team/v1/networks/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": "affiliate"
}
],
"query": {
"filters": [ ]
},
"format": "csv"
}'
Summary
/v1/networks/reporting/entity/summary
The summary endpoint is useful when you are looking to use the powerful features of the table endpoint documented above but you are only looking for top level reporting metrics.
In other words, this endpoint only returns a single reporting metric “row” that will contain the summary of all the data returned by the table endpoint. When using the Everflow UI, you would see this data in the “Summary” section of your report.
While the response from this endpoint is in no way affected by the columns requested, it is still necessary to include them in the request as the endpoint was always intended to be used in conjunction with the table endpoint.
Example
curl --request POST \
--url https://api.eflow.team/v1/networks/reporting/entity/summary \
--header 'Content-Type: application/json' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--data '{
"from": "2022-02-08",
"to": "2022-02-08",
"timezone_id": 67,
"currency_id": "USD",
"columns": [
{
"column": "offer"
}
],
"query": {
"filters": [ ]
}
}'
Response
A single reporting metrics entry :
{
"imp": 0,
"total_click": 82630,
"unique_click": 82630,
"invalid_click": 51484,
"duplicate_click": 0,
"gross_click": 134114,
"ctr": 0,
"cv": 1150,
"invalid_cv_scrub": 21,
"view_through_cv": 0,
"total_cv": 1171,
"event": 611,
"cvr": 1.417,
"evr": 52.178,
"cpc": 0.096,
"cpm": 0,
"cpa": 6.786,
"epc": 0.246,
"rpc": 0.342,
"rpa": 24.113,
"rpm": 0,
"payout": 7946,
"revenue": 28236.05,
"event_revenue": 21709.05,
"gross_sales": 86989,
"profit": 20290.05,
"margin": 71.859,
"roas": 3.081,
"avg_sale_value": 74.286,
"media_buying_cost": 0
}