Aggregate reports, raw event search, and single-event lookup tools.
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.
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. unit is one of count, currency, percent, or ratio (see the percent note under run_performance_report). Entries with is_custom: true are this network’s user-defined custom metrics, returned with their formula — these are distinct from the custom_payout_revenue entity.
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
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. This differs from list_entities, which accepts 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 resolvedtimezone 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.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.
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.Time
Dimension
Description
date
Day (YYYY-MM-DD)
hour
Hour of day (0–23)
hourly
Full datetime rounded to the hour
week
ISO week
month
Month (YYYY-MM)
year
Year
day_of_week
Day of week (0 = Sunday … 6 = Saturday)
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. 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
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). It also carries the same metric_glossary object of inline definitions for the easily-confused metrics.
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 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.
