API Endpoint: Statistics Reports

This page describes how to use the Katalys API to generate an aggregated Statistics Report to download analytics data. You use this method when you want click or behavioral information about your traffic.

URL: https://api.katalys.com/v1/report/stats
Method: POST with a JSON payload
Authentication: Authorization header with a Katalys API key is required
Response: JSON object with keys rows containing your data

Example using cURL:

CODE

curl -H 'Authorization: Apikey YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "dimensions":[...], "filters":[...] }' \
  https://api.katalys.com/v1/report/stats

Limitations

Dimension Cardinality: This use case is primarily focused on driving low-cardinality reporting using dimensions with 20 or fewer values, such as "Device Type" (typically 3-5 values), or "Traffic Source" (typically 5-50 values).

If you run a statistics report and the time range, defined filters or selected dimensions result in a report that cannot be returned fully, then a warning will be included in the response object. Here is an example response showing the warning:

JSON

{
  "rows": [ {}, {}, {}... ],
  "warnings": [
    { "message": "Column \"Product Name\" is limited to 300 items. Add filters to limit your search." }
  ],
  "errors": null
}

If you need full breakdowns, then you must download a raw Conversion Report and produce your own statistics.

Specification

This API method receives a JSON object with the following required objects.

dimensions: Array of strings.
String values are named columns that can be included in a report. Some columns are "statistics", meaning they produce aggregations; other columns are "breakdowns", meaning they change the number of rows returned by breaking down the data.
filters: Array of Filter objects.
Objects must define field, type, and values.
- Filter.field is a string specifying one of the defined available filters.
- Filter.type is "include", "exclude", or "range". The range type is typically used for filtering on time.
- Filter.values is a list of string values. Even numeric types, such as epoch times, must be passed as strings.

To be considered a valid query, every query you make must include:

a filter on the time field
at least one "breakdown" dimension, and
at least one "statistic" dimension.

If you use TypeScript, you can validate your query using the following TypeScript interface.

TYPESCRIPT

export interface KatalysApiRequest {
  dimensions: string[];
  filters: KatalysFilter[];
}
interface KatalysFilter {
  field: string;
  type: KatalysFilterType | `${KatalysFilterType}`;
  values: string[];
}
enum KatalysFilterType {
  INCLUDE = "include",
  EXCLUDE = "exclude",
  RANGE = "range",
}

Permissions for Dimensions

A reporting API request can include Partner-only dimensions, or Advertiser-only dimensions, but not both types at once. If any report includes both Advertiser and Partner dimensions, your request will fail.

The types Partner or Advertiser come from the type of Profiles owned by your Katalys organization. If your account owns an Advertiser profile, then you can select Advertiser dimensions. If your account owns a Partner profile, then you can select Partner dimensions.

If you wish to limit the reporting to just Advertiser-scoped or Publisher-scoped dimensions, it is recommended to define the org_id filter and list the profiles you own of that type. This will ensure the expected permissions match the dimension types you are requesting.

Available Breakdown Dimension

By defining one or more of the below dimensions, you affect how many rows are returned from your query. We recommend limiting the number of breakdown dimensions to no more than 5 to ensure you do not hit the cardinality limit, which can hide some values from the result.

Field	Permissions	Description
`aff`	All types	Name and ID of Traffic Source
`aff_id`	All types	ID of traffic source assigned by the Katalys network
`offer`	All types	Name and ID of program
`offer_id`	All types	ID of program assigned by the Katalys network
`time_day`	All types	Breakdown by day, specified as epoch-milliseconds. Day boundaries are defined by default in the `America/Los_Angeles` timezone. You can adjust these day boundaries by adding a filter on `timezone` (see Filters definitions below).
`time_hour_of_day`	All types	Breakdown by hour-of-day, specified as as a numeric value from `0` to `23`. Hour boundaries are defined by default in the `America/Los_Angeles` timezone, unless you have defined a `timezone` filter (see Filters definitions below).
`landing_page`	All types	The landing page of the last-click attribution associated with the conversion
`device_type`	All types	Type of device used to place the conversion and/or the click.
`days_from_click`	All types	Number of days from click to conversion. Only populated when a click is associated with the conversion or appears in the attribution path
`cost`	Advertisers Only	Total cost to drive conversions within the Katalys network
`product_sku`	Advertisers Only	Product SKU as reported by Advertiser
`product_name`	Advertisers Only	Product Name as reported by Advertiser
`product_category`	Advertisers Only	Product Category as reported by Advertiser
`payout`	Partners Only	The sum owed to Partners as compensation
`aff_sub_1`	Partners Only	Partner-provided field "sub1"
`aff_sub_2`	Partners Only	Partner-provided field "sub2"
`aff_sub_3`	Partners Only	Partner-provided field "sub3"
`aff_sub_4`	Partners Only	Partner-provided field "sub4"
`aff_sub_5`	Partners Only	Partner-provided field "sub5"
`aff_sub_source`	Partners Only	Partner-provided field "source"

Available Statistic Dimensions

Define one or more statistic dimensions below into your API request to add values to each row that is returned.

Field	Permissions	Description
`unique_clicks`	All types	Total number of unique clicks excluding invalid clicks on content within the Katalys network. See How We Count Clicks
`gross_clicks`	All types	Total number of times a customer has clicked on content within the Katalys network.
`impressions`	All types	Number of digital views or engagements with content, if this metric is reported or implemented by the Partner.
`total_orders`	All types	Count of orders placed by any customer, regardless of conversion status
`conversions`	All types	Count of approved conversions
`conversions_no_coupon`	All types	Count of approved conversions attributed to clicks, excluding conversions that were triggered via usage of a coupon solely.
`cr`	All types	Conversion Rate is calculated by `conversions_no_coupon` divided by `unique_clicks`
`sessions_network`	All types	Count of sessions driven by the Katalys network
`unique_ips`	All types	Count of unique IP addresses for all visitors
`order_value`	All types	Derived metric calculating “captured value” using all numbers received from the CRM. Since CRMs calculate subtotal in different ways, we use the lowest value of reported Subtotal, or reported Total minus tax/shipping. Used for calculating CPS.
`topline_sale_amount`	Advertisers Only	Actual cost to customer, via Advertiser's CRM. Typically, gross value of orders inc tax, shipping, and misc line items.
`cost`	Advertisers Only	Total cost to drive conversions within the Katalys network
`sessions`	Advertisers Only	Count of sessions that saw at least one hit. Sessions may or may not have come from the Katalys Network.
`payout`	Partners Only	Amount paid to Partner
`epc`	Partners Only	Partner Earnings Per Click
`eps`	Partners Only	Partner Earnings Per User-session

Available Filters

Field	Valid Types	Description
`time`	`range`	Required for all API calls. Limits your report query to the epoch times specified in the range. Example: `{ "field":"time", "type":"range", "values":["1740457060","1740457900"] }`
`status`	`include` or `exclude`	(Recommended) Limits your report query to include only valid conversions. This will skip rejected conversions and conversions that were processed by Katalys but were not attributed to a Katalys affiliate. Example: `{ "field":"status", "type":"include", "values":["1"] }`
`timezone`	`include`	By specifying this filter, you change how dimensions like `time_day` separate rows. Default reporting timezone is `America/Los_Angeles`. Note: outside of this default, this filter only supports hour-offset syntax, such as `-07:00`. You cannot specify other IANA timezone names using this filter. Example: `{ "field":"timezone", "type":"include", values:[ "-07:00" ] }`
`org_id`	`include`	Limits your results to the specified Profiles. Your Profile’s org_id value can be found in the URL of your KMP account. Example: The URL `https://app.katalys.com/adv/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/dashboard` contains an Advertiser-type Profile ID. When extracted from the URL, it can be used in the `org_id` filter like this: `{ "field":"org_id", "type":"include", "values":["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"] }`