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

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
unix_timestamp Group data in chunks of 15 minutes
event_name Group by event id
offer_url Group by offer url id
country Group by country
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

POST /v1/networks/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”.

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

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

offer, offer_group, affiliate, advertiser, creative, network, account_manager, affiliate_manager, category, billing_frequency, country, region, city, dma, 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, isp, offer_status, sub1, sub2, sub3, sub4, sub5, channel, coupon_code, affiliate_tier

Aggregated data requests also support 3 entirely optional settings :

  • ignore_fail_traffic : defaults to false when omitted – can be used to exclude fail traffic from results
  • only_include_fail_traffic : defaults to false – opposite of the setting above
  • campaign_data_only : defaults to false – 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
    }
  }
}

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

The response from this endpoint varies depending on the columns you requested. The structure will always be the same though, and they 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.

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
            }
        },
        {
            "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
            }
        }
    ]
}

Table Export

POST /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 :

  • csv
  • json

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

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.

Reporting Summary
Reporting summary line in the Everflow UI

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": [ ]
    }
}'

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
}