Get Experiment Performance Statistics
experiment_performance_statsExperiment-level performance statistics from Metadata.io Experiments API.
USE FOR:
Experiment-level metrics (spent, leads, impressions, clicks, cpl, ctr, mql)
Campaign comparisons (A vs B, time periods)
Triggered/influenced opportunities analysis
Pipeline opportunity analysis from campaigns
Campaign ingredients (audience size, channel, audience/ad/offer used)
ROI analysis, trend analysis, top performers
Creative usage by experiments
Filtering by experiment/campaign names
Filtering by launch status via launchedExperimentStatuses (FAILED / DISCONNECTED experiments are excluded by default — see that parameter)
NOT FOR:
Experiment pacing status ("which experiments are underpacing")
Ad-level triggered opportunities
Ingredient-level analysis (use performance_metrics)
RETURNED DATA: spent, clicks, impressions, leads, mqls, cpl, cpc, cpm, ctr | opens, sends, actionClicks, costPerOpen, costPerSend (CONVO/MESSAGE ads) | adTypes (list of ad types in this experiment) | triggeredAmount, oppsAmount, cpMql, mqlRate, conversionRate | experimentName, campaignName, audienceName, offerName, offerType, adName | audienceTypes, audienceSize, channel, goal | imageLibraryName | startDate, endDate, pacing, quarterIndex
CONVO/MESSAGE AD CAVEAT: when adTypes contains CONVO or MESSAGE, success is measured by opens, sends, and actionClicks (and costPerOpen / costPerSend), NOT clicks/ctr/cpc. An experiment with $100K+ spend and 0 clicks where adTypes includes CONVO can be a top performer — assess on the right metric. To rank conversational performance explicitly, use sort='actionClicks,desc' or sort='opens,desc' instead of the lead-gen defaults.
GOAL CAVEAT: every row carries the goal the experiment was launched with ('goal': CPL for Lead Generation, CTR for Brand Awareness / traffic) and, when the platform sends it, its offer type ('offerType': LG is a native lead gen form, LP a landing page offer). A CTR-goal experiment is measured on impressions, clicks, CTR and CPC and captures no leads by design, so leads=0 on it is expected and is NOT a conversion or tracking failure. On a CPL-goal row a landing page offer captures leads through the form the platform requires on it (Google Ads and Reddit have no native form, so their lead gen always runs on an LP offer), so zero leads there is a real funnel question; stats alone cannot tell a broken form or thank-you page from a page that never had a form, so read the offer (get_offer: its goal, form and thank-you page) before naming a cause. A CTR-goal row also carries 'leadCaptureNote' saying exactly this.
LEAD DATES: these rows carry no lead or conversion date. For when an experiment's most recent lead arrived, call get_converted_leads with experimentName set to the row's name and size=1 (sorted creationDate,desc by default; experimentName is a substring match, so confirm the returned lead's experiment). A claim that two lead reports disagree rests on those lead records too, compared over the same window and scope. Where get_converted_leads is unavailable, get_converted_leads_summary with experimentName, startDate and endDate shows whether any lead arrived in a window; otherwise say the date cannot be read from these rows. Never infer a lead date from this report.
LINK FORMAT: /hub/advertise/experiments?name={wizExperimentName}
RULES:
'cpl2Score,desc' for Lead Gen/unspecified, 'cpc2Score,desc' for Brand Awareness
'triggeredAmount,desc' for ROI/pipeline, 'oppsAmount,desc' for influenced pipeline
size=1 for 'top' singular, size=requested for 'top X', size=50 for plural, size=15 default
failed/non-launched experiments are excluded by default; pass launchedExperimentStatuses=['Failed'] ONLY when the user explicitly asks about failures
this layer returns EVERY launched experiment with delivery in the window, including zero-lead and zero-spend ones, unless you set a min* filter yourself. An empty or short result means nothing matched the filters you sent, NOT that campaign-level reporting is broken or stale; re-run without the min* filters before telling the user anything is wrong
the response is ONE page: 'totalElements' is the full match count and 'totalPages' the page count at the requested 'size'. When totalElements exceeds the rows returned, fetch the next 'page' or repeat with a larger 'size' before compiling a full list; re-issuing the identical call returns the identical page
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Experiment name filter, matched as ONE substring per request. Use 'name' field (NOT experimentName) for specific experiment questions. Can be a single string or an array of strings for multiple experiments; an array is queried one name per request and the results are merged. Do NOT add additional parameters when filtering by specific experiment name. | |
| page | No | Page number for pagination (0-based). Use it with the 'size' you already sent to reach rows beyond the first page when 'totalElements' exceeds the rows returned. | |
| size | No | Number of results per page. RULES: size=1 for 'top' singular questions, size=requested number for 'top X' questions, size=50 for plural questions (e.g. 'campaigns'), size=30+ for multiple metrics analysis, size=15 as default when not specified. Raise it freely for full-dataset analytics — there is no small ceiling. | |
| sort | No | Sorting parameter. CRITICAL RULES: 'cpl2Score,desc' for Lead Generation or unspecified campaigns, 'cpc2Score,desc' for Brand Awareness, 'triggeredAmount,desc' for ROI/pipeline questions, 'oppsAmount,desc' for influenced pipeline, 'conversionRate,desc' for conversion rate, 'internalStatus,desc' for active experiments, use specific metric,desc when asked (e.g. 'impressions,desc', 'mqls,desc'). | cpl2Score,desc |
| goals | No | Campaign goal type. RULES: 'CPL' for Lead Generation campaigns, 'CTR' for Brand Awareness campaigns. Do NOT include for unspecified campaign types. When multiple metrics involved, use only the first metric's corresponding goal. | |
| adName | No | Filter by specific ad name (e.g., 'Sifted_WorkShift_Ad5_Beige'). Use 'adName' field when question asks about specific ad names. | |
| minCpc | No | Minimum cost per click threshold (whole dollars). OPTIONAL filter: omit it unless the question needs one. Do NOT set it for Lead Generation or unspecified campaign types. | |
| minCpl | No | Minimum cost per lead threshold (whole dollars). OPTIONAL filter: omit it unless the question needs one. It excludes every zero-lead experiment, whose CPL is undefined, so never pair it with minLeads=0 and never set it for Brand Awareness. | |
| endDate | No | End date in ISO 8601 format. Must end on last hour of date (e.g., '2024-11-21T23:59:59.999Z'). CRITICAL: Do NOT include if timeFrame parameter is used. For specific campaigns/experiments without timeframe, omit this parameter. | |
| metrics | No | List of metrics for secondary ordering when question involves multiple metrics (e.g., ['cpl', 'ctr', 'leads']). Only include when analyzing more than one metric simultaneously. Do NOT include for single metric questions. | |
| channels | No | Marketing channels to include | |
| minLeads | No | Minimum leads threshold. OPTIONAL filter: omit it unless the question needs one. Useful to keep only converting experiments in a Lead Generation ranking. Do NOT set it for Brand Awareness, nor when the user asks about zero-lead or 'no results' experiments. | |
| minSpend | No | Minimum spend threshold. OPTIONAL filter: omit it unless the question needs one. Useful when ranking Lead Generation performance and non-delivering experiments would be noise. Do NOT set it when the user asks about experiments with no spend, no leads or no results. | |
| minClicks | No | Minimum clicks threshold. OPTIONAL filter: omit it unless the question needs one. Useful in a Brand Awareness ranking. Do NOT set it for Lead Generation. | |
| offerName | No | Filter by specific offer name (e.g., 'AMER_ZO_EN_HBR Reimagining Work'). Use this field when question mentions specific offers. | |
| startDate | No | Start date in ISO 8601 format (e.g., '2024-10-18T00:00:00.000Z'). CRITICAL: Do NOT include if timeFrame parameter is used. Use last year of data if period cannot be inferred from question. For specific campaigns/experiments without timeframe, omit this parameter. | |
| timeFrame | No | Timeframe aggregation. CRITICAL RULES: Use ONLY for WEEK or QUARTER questions. NEVER use 'YEAR' - use startDate/endDate instead. If timeFrame is included, DO NOT add startDate or endDate parameters under any circumstances. | |
| offerTypes | No | Offer types filter. RULES: ['LP'] for lead gen forms/landing pages questions, ['LP', 'LG'] as default when offer types mentioned. LP=Landing Pages, LG=Lead Gen forms. Should NOT be empty when included. | |
| audienceName | No | Filter by target audience name (e.g., 'WTS EMEA Jan25_EMEAPitchbook') | |
| campaignName | No | Campaign name filter. Use when question is about specific campaign(s). Can be single string or array ['campaign1', 'campaign2'] for multiple campaigns. Do NOT include additional parameters when filtering by specific campaign name. | |
| visibilities | No | Visibility status filter. The platform knows only VISIBLE (live) and ARCHIVED; there is no HIDDEN value and sending one is rejected with a 400. | |
| audienceTypes | No | Comma-separated list of audience types (e.g., 'Spotlight Retargeting Contacts (Dynamic),Technographic (Aberdeen)') | |
| minAudienceSize | No | Minimum audience size. OPTIONAL filter: omit it unless the question needs one. | |
| imageLibraryName | No | Filter by creative/image name (e.g., 'JP - Square-Ad15.png'). Use 'imageLibraryName' field when question asks about specific creative names. | |
| launchedExperimentStatuses | No | Filter experiments by launch status. DEFAULT when omitted: successfully-launched experiments only (Active, WithoutSpend, Paused, Completed) — Failed and Disconnected are EXCLUDED, because a failed/non-launched experiment has 0 leads and is a non-starter, not a 'bottom performer'. Pass values explicitly to override: ['Active'] for live only, or ['Failed'] / ['Failed','Disconnected'] when the user explicitly asks which experiments failed. |