Reporting - Everflow API

Which reporting tool should I use?

Aggregated stats (totals, trends, breakdowns) → run_performance_report or run_network_summary
Raw event records (individual clicks or conversions over a window) → search_activity (set type to click or conversion)
Single event by ID (attribution troubleshooting, dispute resolution) → get_entity with type="click", type="conversion", or type="transaction" (full attribution chain). See Events & Attribution.

get_report_schema

Returns the complete list of valid dimension keys, filter keys, and metric names for run_performance_report, plus an authoritative definition for every metric. Call this first if you’re unsure which keys to use — the exact strings returned here are the accepted values for dimensions, filters, and sort_by. It is also the source of truth for “what metrics are available?”, “how is <metric> calculated?”, and “what custom metrics do I have?”. Parameters: None. Response fields:

Field	Type	Description
`columns`	array	Valid dimension keys for the `dimensions` parameter
`filters`	array	Valid filter keys for the `filters` parameter
`metrics`	array	Valid metric names for `sort_by` — also returned in every report row
`metric_definitions`	array	One entry per metric, each `{ name, description, unit, formula, is_custom }`

The metric_definitions entries describe how each metric is computed. For built-in metrics, unit is one of count, currency, percent, or ratio, and the human-readable formula is in the description (the formula field itself may be empty). For custom metrics (is_custom: true — this network’s user-defined metrics), the formula field is populated but unit may be empty. Custom metrics are distinct from the custom_payout_revenue entity.

run_performance_report

Queries aggregated performance data grouped by one or more dimensions. The primary tool for campaign analysis, partner comparison, and revenue reporting. Parameters:

Parameter	Type	Required	Description
`from`	string	Yes	Start date (`YYYY-MM-DD`)
`to`	string	Yes	End date (`YYYY-MM-DD`)
`dimensions`	string	Yes	Comma-separated dimensions (see below) — max 256 chars
`filters`	string	No	Comma-separated inclusive `type:value` pairs — e.g. `offer:123,affiliate:456` — max 4,096 chars total; sub-param values (`sub1`–`sub10`, `adv1`–`adv10`, `source_id`) max 600 chars each. Match several IDs for one ID filter by separating them with `\|` — e.g. `offer:1\|2\|5`. Only inclusive filters are supported — there is no exclusion syntax.
`metric_filters`	string	No	Numeric conditions on the aggregated metric values — comma-separated, ANDed, max 10. E.g. `clicks>100,cvr<2` or `invalid_clicks<=0`. Operators: `>`, `>=`, `<`, `<=`. The left side must be a metric name (not a dimension); use `conversions`, not `cv`. Applied after aggregation, before sorting and pagination. — max 512 chars
`sort_by`	string	No	Metric name to sort by (see metrics accordion below) — max 128 chars
`sort_direction`	string	No	`asc` or `desc` (default: `desc`) — max 8 chars
`timezone`	string	No	IANA timezone name. Defaults to the network timezone (matches the Everflow portal) — max 64 chars
`currency`	string	No	Currency code. Defaults to the network’s base currency — max 8 chars
`page_size`	number	No	Rows per page (1–100, default 50)
`cursor`	string	No	Pagination cursor from a prior response — max 1,024 chars
`comparison`	string	No	Set to `previous_period` to compare `[from, to]` against the equal-length window immediately before it. Enables comparison mode (see below).
`compare_from`	string	No	Explicit comparison-baseline start (`YYYY-MM-DD`). Use with `compare_to` for an arbitrary prior window instead of `comparison`.
`compare_to`	string	No	Explicit comparison-baseline end (`YYYY-MM-DD`). Must be paired with `compare_from`.

The filters parameter uses comma-separated type:value strings — for example offer:123,affiliate:456,country_code:US. To match multiple values for the same ID filter, separate them with a pipe — offer:1|2|5 returns all three offers in a single query instead of running a separate report per offer. The type:value string form is the documented, preferred form here; a JSON-object form (e.g. {"offer":"1|2"}) is also accepted but should not be mixed with the string form in one call. (list_entities, by contrast, accepts only a JSON object.) See the filters accordion below for all valid keys.

filters and metric_filters are different axes. filters narrows by dimension/entity values (offer, affiliate, country, sub1, …); metric_filters narrows by metric values (clicks, conversions, invalid_clicks, revenue, cvr, …). A metric name is not a valid filters key, and vice-versa.Percent metrics: cvr, ctr, and margin are expressed as percentages (e.g. 2.84 means 2.84%), not 0–1 fractions. In metric_filters, write cvr<2 to mean “CVR under 2%”. For “no invalid traffic”, use invalid_clicks<=0.

Response envelope:

run_performance_report uses total_rows (not total_matching) in its pagination envelope, which differs from list tools like list_offers and list_affiliates.

Field	Type	Description
`next_cursor`	string	Pass as `cursor` to retrieve the next page. Absent when there are no further pages.
`rows_returned`	number	Number of rows in this page
`total_rows`	number	The true number of rows matching the query, before any cap. When `result_capped` is `true` this exceeds the number you can page to.
`has_more`	boolean	`true` when more pages exist for this query — fetch them by passing `next_cursor` back as `cursor`. This is ordinary pagination, not missing data.
`result_capped`	boolean	`true` when the query matched more than the hard row limit and rows were dropped. Unlike `has_more`, paging every page will not return them — narrow the date range, add filters, or use fewer dimensions.
`row_limit`	number	Present only when `result_capped` is `true` — the maximum rows the tool will return for one query (the cap that dropped rows).

has_more and result_capped are independent. has_more: true alone just means “page for the rest.” result_capped: true means the result is genuinely incomplete — to get complete data, narrow the date range, add more specific filters (e.g. a single affiliate or offer), or split the request into multiple smaller queries.

The response also carries an applied_query object — the exact, resolved query that produced the rows, so you can audit a number and reproduce it in the portal rather than trust it blind. It echoes from, to, the resolved timezone and currency (after defaulting to the network’s settings when omitted), dimensions, and — when supplied — filters, metric_filters, and sort_by/sort_direction. Empty sections are omitted.

Timezone resolution. Everflow supports a fixed set of timezones. If you request a valid IANA zone that isn’t in that set, it’s resolved to the supported zone with identical day boundaries and DST rules (e.g. America/Toronto → America/New_York) — the numbers are unaffected. When this happens, applied_query additionally carries timezone_requested (what you asked for) and a timezone_note explaining the mapping, so the resolved timezone isn’t mistaken for the request being ignored.

It also carries a metric_glossary object — inline one-line definitions for the metrics that are easy to misread, so methodology travels with the numbers instead of needing a separate get_report_schema call. It covers the conversion-counting family (conversions vs total_conversions vs events), revenue’s event inclusion, and the percent/ratio metrics (cvr, ctr, margin, roas) so 2.84 isn’t mistaken for a fraction. And a totals object with every metric aggregated over the full matched set — all rows, before pagination and the display cap — computed server-side so you never sum rows yourself. Additive metrics (clicks, conversions, payout, revenue, …) are summed; the ratio metrics (cvr, roas, margin, …) are re-derived from those sums (e.g. overall cvr = Σtotal_conversions ÷ Σclicks), never averaged — so the totals stay correct even when only one page of rows is returned.

Period-over-period comparison

To answer “which offers/partners moved the most”, have the report compare two periods instead of running it twice and subtracting the numbers yourself. Set comparison=previous_period (compares [from, to] against the equal-length window immediately before it) or pass an explicit compare_from/compare_to baseline (e.g. the same month last year). Each row then carries, for every metric, an object of { current, prior, delta, pct_change } — all computed server-side. pct_change is null when the prior value was 0 (the change is undefined, not an infinite increase). Rank the movers with a delta sort key: sort_by accepts <metric>_delta and <metric>_pct_change (e.g. epc_delta, revenue_pct_change) in addition to the raw metric names.

run_performance_report(
  from="2026-07-01", to="2026-07-14",
  dimensions="offer", filters="affiliate:3296",
  comparison="previous_period", sort_by="epc_delta"
)
→ offers this partner runs, ranked by the change in EPC vs 2026-06-17–2026-06-30

Comparison mode is current-anchored. It ranks rows that were active in the current period against their prior-period values. An entity that had activity in the prior period but none in the current period is not returned — so comparison mode cannot answer “what did I lose”. For that, run an explicit report over the prior window on its own.Comparison mode requires sort_by, does not support cursor (no pagination across a join), and cannot group by a time dimension (date, hour, month — a date never aligns across two windows). It is also bounded: if either period matches more rows than the comparison cap, the call returns an error asking you to narrow — add metric_filters (e.g. revenue>1000), add filters, or use fewer dimensions, rather than expecting truncation. The prior period is fetched scoped to the current period’s entities, so for single-dimension comparisons narrowing the current period is enough. With multiple dimensions the prior scope is per-dimension (a cross-product of the current ids), so a very active prior period can still exceed the cap — narrow further with filters or drop a dimension if it does.

Don’t add up the rows yourself for a total — use totals. Row-level ratio metrics cannot be summed or averaged into an overall figure, and summing a single page misses the rest of the result set. totals handles both correctly.

Available dimensions

Pass one or more of these keys as a comma-separated dimensions string. The schema (get_report_schema) also returns two aliases not listed below: smart_link (alias of campaign) and device (a general device dimension alongside device_type).Time

Dimension	Description
`date`	Day (YYYY-MM-DD)
`hour`	Per-hour timestamp bucket (e.g. `2026-07-14 15`) — one row per distinct hour in the range
`hourly`	Hour of day (0–23, as `HH:00`) — aggregated across the whole range; use for peak-hour / time-of-day analysis
`week`	ISO week
`month`	Month (YYYY-MM)
`year`	Year
`day_of_week`	Day of week as a name (`Monday`…`Sunday`), aggregated across the range

Entities

Dimension	Description
`offer`	Offer name
`offer_id`	Offer ID
`affiliate`	Affiliate name
`affiliate_id`	Affiliate ID
`advertiser`	Advertiser name
`advertiser_id`	Advertiser ID
`campaign`	Smart link / campaign name
`campaign_id`	Campaign ID
`smart_link`	Alias of `campaign`
`creative`	Creative name
`creative_id`	Creative ID
`offer_group`	Offer group name
`offer_group_id`	Offer group ID
`offer_url`	Offer URL
`offer_status`	Offer status
`affiliate_status`	Affiliate status
`originating_offer`	Originating offer in a redirect chain
`category`	Offer category
`network`	Network identifier
`source_id`	Traffic source ID
`event_name`	Conversion event name
`advertiser_event_name`	Advertiser-side event name
`advertiser_campaign_name`	Advertiser campaign name

Geo

Dimension	Description
`country`	Country name
`country_code`	ISO 2-letter country code
`region`	Region / state
`city`	City
`dma`	Designated market area (US only)
`postal_code`	Postal code

Device & Technology

Dimension	Description
`browser`	Browser name
`platform`	OS platform
`device_type`	Device type (desktop, mobile, tablet)
`device`	Alias of `device_type`
`device_make`	Device manufacturer
`device_model`	Device model
`os_version`	OS version string
`language`	Browser language
`connection_type`	Connection type (wifi, cellular, etc.)
`carrier`	Mobile carrier
`isp`	Internet service provider
`is_proxy`	Whether traffic came through a proxy
`meta_platform`	Meta / Facebook platform

Tracking & Attribution

Dimension	Description
`tracking_domain`	Custom tracking domain
`transaction_id`	Raw transaction ID
`attribution_method`	Attribution method
`order_id`	Order ID passed on conversion
`coupon_code`	Coupon code
`referer`	Referring URL
`click_error_code`	Click error code
`conversion_error_code`	Conversion error code

People & Managers

Dimension	Description
`affiliate_manager`	Affiliate manager name
`account_manager`	Account manager name
`sales_manager`	Sales manager name
`account_executive`	Account executive name
`customer_support_manager`	Customer support manager name
`admin_account_manager`	Admin account manager name

Payout & Revenue

Dimension	Description
`payout_type`	Payout model (CPA, CPC, etc.)
`payout_amount`	Payout amount
`revenue_type`	Revenue model
`revenue_amount`	Revenue amount
`currency`	Currency code
`custom_payout_revenue`	Custom payout/revenue rule name
`custom_payout_revenue_id`	Custom payout/revenue rule ID

Sub-Parameters

Dimension	Description
`sub1`–`sub10`	Affiliate sub parameters (pass separately: `sub1`, `sub2`, …)
`adv1`–`adv10`	Advertiser sub parameters (pass separately: `adv1`, `adv2`, …)

App

Dimension	Description
`project_id`	App project ID
`app_identifier`	App identifier
`bundle_id`	App bundle ID

Available filters

Pass filters as comma-separated inclusive type:value pairs — e.g. offer:123,affiliate:456,country_code:US. Only inclusive filters are supported — there is no exclusion syntax. status is not a supported filter or dimension on this tool; to filter conversions by status, use search_activity(type="conversion") instead.Multiple values (OR): for any ID filter, separate IDs with a pipe to match any of them in one query — offer:1|2|5 returns offers 1, 2, and 5 together. Repeating a key (offer:1,offer:2) does the same. Supported on the ID filters: offer, offer_group, affiliate, advertiser, creative, campaign, category, network, tracking_domain, channel. Prefer one multi-value query over many single-ID queries.Accepted aliases: the _id form and common synonyms are normalized to the canonical key, so you don’t have to guess — offer_id→offer, affiliate_id/partner→affiliate, advertiser_id/brand→advertiser, offer_group_id→offer_group, campaign_id/smart_link→campaign, and the error-code dimensions click_error_code/conversion_error_code→error_code (so you can filter by the same key you grouped a breakdown on). An unrecognized filter key returns an error with a suggestion rather than being silently ignored. Note: campaign is the smart-link/rotator entity; the individual ad campaign is an offer.Entities

Filter	Value format	Example
`offer`	Numeric offer ID	`offer:123`
`offer_group`	Numeric offer group ID	`offer_group:45`
`affiliate`	Numeric affiliate ID	`affiliate:678`
`advertiser`	Numeric advertiser ID	`advertiser:99`
`creative`	Numeric creative ID	`creative:12`
`campaign`	Numeric campaign ID	`campaign:7`
`category`	Numeric category ID	`category:3`
`network`	Numeric network ID	`network:1`
`source_id`	String	`source_id:google`
`event_name`	String	`event_name:purchase`
`offer_url`	Numeric URL ID	`offer_url:8`
`offer_status`	`active`, `paused`, `pending`, `deleted`	`offer_status:active`
`originating_offer`	Numeric offer ID	`originating_offer:123`
`transaction_id`	32-char hex string	`transaction_id:abc123...`
`error_code`	Numeric error code	`error_code:0`
`coupon_code`	String	`coupon_code:SUMMER20`
`tracking_domain`	Numeric domain ID	`tracking_domain:5`
`channel`	Numeric channel ID	`channel:2`

Geo — region/city take internal numeric IDs; resolve a name to its ID with list_entities (type=region / type=city, and type=country for the country_id that scopes a region lookup).

Filter	Value format	Example
`country`	ISO 2-letter code (resolve names via `list_entities` type=country)	`country:US`
`country_code`	ISO 2-letter code	`country_code:US`
`region`	Numeric region ID (resolve via `list_entities` type=region)	`region:1140`
`city`	Numeric city ID (resolve via `list_entities` type=city, which requires `region_id`)	`city:534`

Device & Technology

Filter	Value format	Example
`browser`	Browser name	`browser:Chrome`
`device_type`	`desktop`, `mobile`, `tablet`	`device_type:mobile`
`device_platform`	Platform string	`device_platform:iOS`
`device_make`	Manufacturer name	`device_make:Apple`
`device_model`	Model name	`device_model:iPhone 15`
`carrier`	Carrier name	`carrier:Verizon`
`language`	Browser language code	`language:en-US`
`connection_type`	Connection type string	`connection_type:wifi`

People & Managers — numeric employee IDs; resolve a name with list_entities type=employee.

Filter	Value format	Example
`account_manager`	Numeric employee ID	`account_manager:55`
`affiliate_manager`	Numeric employee ID	`affiliate_manager:12`
`sales_manager`	Numeric employee ID	`sales_manager:8`
`account_executive`	Numeric employee ID	`account_executive:3`

Sub-Parameters

Filter	Value format	Example
`sub1`–`sub10`	String	`sub1:source_a`
`adv1`–`adv10`	String	`adv1:campaign_x`

Billing & Labels

Filter	Value format	Example
`label`	Label name	`label:top_affiliate`
`business_unit`	Business unit name	`business_unit:retail`
`affiliate_tier`	Tier name	`affiliate_tier:gold`
`billing_frequency`	Frequency string	`billing_frequency:monthly`
`advertiser_billing_frequency`	Billing frequency	`advertiser_billing_frequency:weekly`

Available metrics

These are also the valid values for the sort_by parameter. Call get_report_schema for the same definitions in machine-readable form (metric_definitions), including any network-specific custom metrics.Volume

Metric	Description
`impressions`	Ad impressions served
`gross_clicks`	All clicks before dedup/validation
`clicks`	Total valid clicks (post-dedup)
`unique_clicks`	Distinct clicks within the dedup window
`duplicate_clicks`	Clicks dropped as duplicates
`invalid_clicks`	Clicks rejected by validation (geo, cap, fraud, …)
`conversions`	Base conversions; excludes scrubbed and view-through
`total_conversions` / `total_cv`	Conversions + scrubbed + view-through (does not include events)
`events`	Additional conversion events beyond the base conversion

Revenue & Cost

Metric	Description
`payout`	Amount paid to partners
`revenue`	Revenue from advertisers, including event revenue
`profit`	`revenue − payout`
`gross_sales`	Sale amount attributed to conversions
`media_buying_cost`	Partner-reported media buying cost

Rates & Efficiency

Metric	Description
`ctr`	Click-through rate = `clicks ÷ impressions` (percent)
`cvr`	Conversion rate = `total conversions ÷ clicks` (percent)
`epc`	Earnings per click = `(revenue − payout) ÷ clicks`
`rpc`	Revenue per click = `revenue ÷ clicks`
`cpa`	Cost per acquisition = `payout ÷ conversion`
`cpc`	Cost per click = `payout ÷ clicks`
`cpm`	Cost per thousand impressions = `payout × 1000 ÷ impressions`
`roas`	Return on ad spend = `gross_sales ÷ revenue` (ratio)
`margin`	`(revenue − payout) ÷ revenue` (percent)

cvr, ctr, and margin are percentages (e.g. 2.84 = 2.84%), and roas is a ratio. This matters in metric_filters: cvr<2 means “under 2%“.

run_network_summary

Returns headline performance totals for a date range — no grouping, just aggregate numbers. Optionally includes a comparison against the prior equivalent period, and can be scoped to specific entities. Parameters:

Parameter	Type	Required	Description
`from`	string	Yes	Start date (`YYYY-MM-DD`)
`to`	string	Yes	End date (`YYYY-MM-DD`)
`timezone`	string	No	IANA timezone name. Defaults to the network timezone (matches the Everflow portal) — max 64 chars
`currency`	string	No	Currency code. Defaults to the network’s base currency — max 8 chars
`include`	string	No	`comparison` — adds prior-period metrics for delta analysis — max 256 chars
`filters`	string	No	Scope the totals to specific entities — comma-separated `type:value` pairs. Supported keys: `offer`, `affiliate`, `advertiser`, `creative`, `campaign` (pipe for OR, e.g. `offer:1\|2`). Applied to the comparison period too. — max 4,096 chars

filters enables a filtered period comparison — pair it with include=comparison to answer “is offer 91 up or down vs last week?”. Only the entity keys above are supported here; for breakdowns by country / device / sub-parameter / error-code, use run_performance_report instead — those dimensions are not available on the summary.

Like run_performance_report, the response carries an applied_query object echoing exactly what ran — from, to, the resolved timezone and currency, and any filters and include — so the totals can be audited and reproduced (empty sections omitted). Timezone resolution works the same way here (a requested zone that isn’t supported maps to its equivalent, surfaced via timezone_requested/timezone_note — see the note under run_performance_report). It also carries the same metric_glossary object of inline definitions for the easily-confused metrics.

search_activity

Searches raw event records within a date-time window. Set type to choose the event stream:

type="click" — raw click events. Maximum 14-day window, up to 1,000 records (not paginated).
type="conversion" — conversion events. Minimum reliable window is one full day in the network timezone. Paginated via page_size (1–100, default 50) and next_cursor.

Pagination differs by type. type="conversion" is paginated — request page_size (1–100, default 50) and, while the response has has_more: true, pass its next_cursor back as cursor (with the same filters and window) to fetch the next page. type="click" is not paginated — it returns a single result set capped at 1,000 records, sorted most-recent first. For aggregated counts instead of raw records, use run_performance_report.

Results are automatically filtered by affiliate visibility. If your account has a limited affiliate scope, rows for affiliates outside that scope are silently excluded — counts may be lower than expected when querying without an affiliate_id filter.

Common parameters:

Parameter	Type	Required	Description
`type`	string	Yes	`click` or `conversion` — selects the event stream
`from`	string	Yes	Start datetime (`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`)
`to`	string	Yes	End datetime
`offer_id`	string	No	Filter by offer ID — max 64 chars
`affiliate_id`	string	No	Filter by affiliate ID — max 64 chars
`advertiser_id`	string	No	Filter by advertiser ID — max 64 chars
`country`	string	No	Filter by 2-letter ISO country code — max 64 chars
`sub1`–`sub10`	string	No	Filter by sub parameter value — max 600 chars each
`source_id`	string	No	Filter by traffic source ID — max 600 chars

Type-specific parameters:

Parameter	Applies to	Description
`error_code`	`type="click"`	Filter by click error code
`status`	`type="conversion"`	`approved`, `pending`, `rejected`, `invalid` (case-insensitive; an unrecognized value returns an error rather than being ignored)
`event_name`	`type="conversion"`	Filter to conversions of a named post-conversion event (matched by name, e.g. `Purchase`). Base conversions have no event name.
`adv1`–`adv10`	`type="conversion"`	Filter by advertiser sub parameter value — max 600 chars each
`order_id`	`type="conversion"`	Filter by the merchant order ID recorded on the conversion
`page_size`	`type="conversion"`	Records per page (1–100, default 50)
`cursor`	`type="conversion"`	Pagination cursor from a prior response — pass it back to fetch the next page (reuse the same filters and window)

The window is interpreted in the network’s timezone (matching run_performance_report / run_network_summary). For type="click" the maximum window is 14 days. For type="conversion" the minimum reliable window is one full day (YYYY-MM-DD 00:00:00 to YYYY-MM-DD 23:59:59); shorter windows may return an error. Passing a filter that doesn’t apply to the chosen type (e.g. status with type="click") returns an error.

Response envelope:

Field	Type	Description
`clicks` / `conversions`	array	Array of records, keyed by the requested `type`
`returned`	number	`type="conversion"` — records returned in this page
`page_size`	number	`type="conversion"` — the page size applied to this request
`has_more`	boolean	`type="conversion"` — `true` when more records match; pass `next_cursor` back as `cursor` to page
`next_cursor`	string	`type="conversion"` — cursor for the next page; empty on the last page
`total`	number	`type="click"` — records returned
`capped_at`	number	`type="click"` — hard ceiling applied (`1000`)
`truncated`	boolean	`type="click"` — `true` when more clicks matched than were returned (hit the cap)
`total_matching`	number	`type="click"` — the true number of matching clicks when `truncated`
`note`	string	Guidance when more records exist — page with `next_cursor` (conversions), or narrow filters/window, or use `run_performance_report` (e.g. `dimensions=click_error_code` / `conversion_error_code`) for counts and breakdowns instead of paging raw events

Per-record fields (type="click"): transaction_id, timestamp, offer_id, affiliate_id, advertiser_id, campaign_id, error_code, is_unique, payout, revenue, currency, country, sub1–sub10, source_id. campaign_id is returned only when the click is on a smart link. Per-record fields (type="conversion"): conversion_id, transaction_id, timestamp, click_timestamp, status, error_code, offer_id, offer_name, affiliate_id, affiliate_name, advertiser_id, advertiser_name, payout, revenue, sale_amount, event_id, order_id, country, sub1–sub10, source_id. Fields that are empty/zero are omitted — coupon_code, is_scrub, event_name, and adv1–adv10 appear only when populated.

Single-event & transaction lookup

Single-event lookups are served by the generic get_entity tool (type="click", type="conversion", or type="transaction" for the full attribution chain). Response fields, listing filters, and guidance on choosing between these and search_activity are on Events & Attribution.

​get_report_schema

​run_performance_report

​Period-over-period comparison

​run_network_summary

​search_activity

​Single-event & transaction lookup

get_report_schema

run_performance_report

Period-over-period comparison

run_network_summary

search_activity

Single-event & transaction lookup