Brand Lift Results

To get results related to your study setup, use <STUDY_ID> to make the same API calls listed in the Conversion Lift API Specs.

To get brand lift data related to the study setup, such as question_type, question_text, desired_answer_text, and other information related to your brand request, follow this example API call:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>'  \ https://graph.facebook.com/<API_VERSION>/<STUDY_ID>?fields=objectives{brand_requests{countries,questions,region}}

To retrieve ad-specific data, such as optimization_goal, see the Ads Insight API.

Retrieve objective_ids with study_id

You can read the objectives that were created for a study by making a call to the study's objectives.

curl -G \
	-d 'access_token=<ACCESS_TOKEN>'  \
	https://graph.facebook.com/<API_VERSION>/<STUDY_ID>?fields=objectives

These are the results:

{
  "objectives": {
    "data": [
      {
        "id": "10323698873994785",
        "name": "Multi-Cell Brand Lift 2020",
        "type": "BRAND",
        ...
      },
      ...
    ],
    ...
  },
  ...
}

Retrieve Study Results with objective_id

To retrieve results for an objective, you can make a GET call to the objective node by specifying results in the fields parameter. The last_updated_results field also tells you when the results data was last updated.

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
	https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results, last_updated_results

The resulting data is a JSON object, containing strings with the following default fields:

Field NameUser-friendly Metric NameField DescriptionCalculation Method

cell_id

Cell ID

Cell ID

N/A

experiment_id

Experiment ID

Experiment run for every poll question in each cell; for example, a brand lift study with 2 cells and 3 poll questions have 2*3=experiments.

raw data

population.test

Group Size (Test)

Number of people in the test group for the lift test.

raw data

population.control

Group Size (Control)

Number of people in the control group of the lift test.

raw data

population.reached

Reach

Number of people exposed to the ads during the campaign.

raw data

impressions

Impressions

Number of billable ad impressions for ads in the lift test.

raw data

frequency

Average Frequency

Average number of times ads in the lift test were displayed to each person in the reached population.

impressions / population.reach

responders.test

Responses (Test)

Total number of poll responses collected from the test group.

raw data

responders.control

Responses (Control)

Total number of poll responses collected from the control group.

raw data

scoreSum.test

Desired Responses (Test)

Number of poll responses with the desired answers from the test group.

raw data

scoreSum.control

Desired Responses (Control)

Number of poll responses with the desired answers from the control group.

raw data

scoreSum. incremental

Desired Responses Lift

Net increase in number of desired poll responses as a result of the ads in the lift test.

scoreSum.test - scoreMean.control * responders.test

scoreMean.test

Desired Response Percent (Test)

Percent of the test group who responded with the desired answers.

scoreSum.test / responders.test

scoreMean.control

Desired Response Percent (Control)

Percent of the control group who responded with the desired answers.

scoreSum.control / responders.control

scoreMean. incremental

Brand Lift Percent

Net increase in the percent of the test group with desired poll responses as a result of the ads in the lift test.

scoreMean.test - scoreMean.control

breakthroughs.test

Scaled Desired Responses (Test)

Estimated number of people in the test group who would provide the desired answers to the poll question.

scoreMean.test * population.reached

breakthroughs. control

Scaled Desired Responses (Control)

Estimated number of people in an equally sized control group who would provide the desired answers to the poll question.

scoreMean.control * population.reached

breakthroughs. incremental

Brand Lift

Net increase in the number of people in the test group who would provide the desired answers to the poll question as a result of the ads in the lift test.

breakthroughs.test - breakthroughs. control

breakthroughs. pValue

Brand Lift PValue (Frequentist)

Based on regression analysis, the p–value associated with the brand lift estimate.

(See description)

costPer Incremental Breakthrough

Cost Per Brand Lift

Estimated ad spend per additional person who would provide the desired answers to the poll question as a result of the ads in the lift test.

spend / breakthroughs. incremental

spend

Ad Spend

Total amount spent up to the current time for your lift test.

raw data

costPer Incremental Breakthrough Region

Cost Per Brand Lift Region Benchmark

Average cost per brand lift for other advertisers in the same geographical region.

(See description)

costPer Incremental Breakthrough Vertical

Cost Per Brand Lift Vertical Benchmark

Average cost per brand lift for other advertisers in the same industry vertical.

(See description)

costPer Incremental Breakthrough Vertical

Cost Per Brand Lift Vertical Benchmark

Average cost per brand lift for other advertisers in the same industry vertical.

(See description)

scoreMean Region

Brand Lift Percent Region Benchmark

Average brand lift percent for other advertisers in the same geographical region.

(See description)

scoreMeanVertical

Brand Lift Percent Vertical Benchmark

Average brand lift percent for other advertisers in the same industry vertical.

(See description)

isWinner.is_winner

Is This Cell Winner for Cost Per Brand Lift (Bayesian)

Boolean flag indicating that this test cell has the highest probability of lowest cost per brand lift across all cells in the lift test using Bayesian statistics with an uninformative prior distribution. (Value is 0 when study is single cell or if confidence level below 60% confidence threshold for multi cell),

(See description)

isWinner. confidence_level

Percent Chance This Cell Is Winner for Cost Per Brand Lift (Bayesian)

Probability that the ads in this test cell had the lowest cost per brand lift across all cells in the lift test using Bayesian statistics with an uninformative prior distribution. (Value is –1 when study is single cell or if confidence level below 60% confidence threshold for multi cell).

(See description)

breakthroughs. singleCellBayesian Confidence

Percent Chance of Positive Brand Lift (Bayesian)

Probability that the ads in this test cell caused positive brand lift using Bayesian statistics with an uninformative prior distribution.

(See description)

advanced ScoreSum.test

Desired Responses (Test) (Advanced)

Number of poll responses with the desired answers from the test group after applying advanced adjustments.

raw data

advanced ScoreSum.control

Desired Responses (Control) (Advanced)

Number of poll responses with the desired answers from the control group after applying advanced adjustments.

raw data

advanced ScoreSum. incremental

Desired Responses Lift (Advanced)

Net increase in number of desired poll responses as a result of the ads in the lift test after applying advanced adjustments.

advanced ScoreSum.test - advanced ScoreMean. control * responders. test

advanced ScoreMean. test

Desired Response Percent (Test) (Advanced)

Percent of the test group who responded with the desired answers after applying advanced adjustments.

(See description)

advanced ScoreMean.control

Desired Response Percent (Control) (Advanced)

Percent of the control group who responded with the desired answers after applying advanced adjustments.

(See description)

advanced ScoreMean. incremental

Brand Lift Percent (Advanced)

Net increase in the percent of the test group with desired poll responses as a result of the ads in the lift test after applying advanced adjustments.

advanced ScoreMean.test - advanced ScoreMean. control

advanced Breakthroughs.test

Scaled Desired Responses (Test) (Advanced)

Estimated number of people in the test group who would provide the desired answers to the poll question after applying advanced adjustments.

advanced ScoreMean.test * population.reached

advanced Breakthroughs. control

Scaled Desired Responses (Control) (Advanced)

Estimated number of people in an equally sized control group who would provide the desired answers to the poll question after applying advanced adjustments.

advanced ScoreMean.control * population.reached

advanced Breakthroughs. incremental

Brand Lift (Advanced)

Net increase in the number of people in the test group who would provide the desired answers to the poll question as a result of the ads in the lift test after applying advanced adjustments.

advanced Breakthroughs.test - advanced Breakthroughs. control

advanced Breakthroughs .informative SingleCell Bayesian Confidence

Percent Chance of Positive Brand Lift (Advanced Bayesian)

Probability that the ads in this test cell caused positive brand lift using Bayesian statistics after applying advanced adjustments.

(See description)

advanced CostPer Incremental Breakthrough

Cost Per Brand Lift (Advanced)

Estimated ad spend per additional person who would provide the desired answers to the poll question as a result of the ads in the lift test after applying advanced adjustments.

spend /
breakthroughs. incremental

advanced BrandLiftCI Lower

Credible Interval lower bound

Credible Interval lower bound (thresholds: 5%–95%)

(See description)

advanced BrandLiftCI Upper

Credible Interval upper bound

Credible interval upper bound (thresholds: 5%–95%)

(See description)

advanced IsWinner.is_ winner

Is This Cell Winner for Cost Per Brand Lift (Advanced Bayesian).

Boolean flag indicating that this test cell has the highest probability of lowest cost per brand lift across all cells in the lift test using Bayesian statistics after applying advanced adjustments. (Value is null when study is single cell, 0 if confidence level is below 60% confidence threshold).

(See description)

advanced IsWinner. confidence_ level

Percent Chance This Cell Is Winner for Cost Per Brand Lift (Advanced Bayesian).

Probability that the ads in this test cell had the lowest cost per brand lift across all cells in the lift test using Bayesian statistics after applying advanced adjustments. Threshold: 60%. (Value is null when study is single cell).

(See description)

topNAdsId1

Ad ID Ranked 1 by Spend in Test

Facebook Ad ID for top ranked ad in the lift test by spend.

N/A

topNAds Spend Percentage1

Spend Percent Share for Rank 1 Ad in Test

Percent share of the top ranked ad from the total ad spend in the lift test.

(See description)

topNAdsId2

Ad ID Ranked 2 by Spend in Test

Facebook Ad ID for top ranked ad in the lift test by spend.

N/A

topNAds pend Percentage2

Spend Percent Share for Rank 2 Ad in Test

Percent share of the top ranked ad from the total ad spend in the lift test.

(See description)

topNAdsId3

Ad ID Ranked 3 by Spend in Test

Facebook Ad ID for top ranked ad in the lift test by spend.

N/A

topNAds Spend Percentage3

Spend Percent Share for Rank 3 Ad in Test

Percent share of the top ranked ad from the total ad spend in the lift test.

(See description)

topNAdsId4

Ad ID Ranked 4 by Spend in Test

Facebook Ad ID for top ranked ad in the lift test by spend.

N/A

topNAds Spend Percentage4

Spend Percent Share for Rank 4 Ad in Test

Percent share of the top ranked ad from the total ad spend in the lift test.

(See description)

topNAdsId5

Ad ID Ranked 5 by Spend in Test

Facebook Ad ID for top ranked ad in the lift test by spend.

N/A

topNAds Spend Percentage5

Spend Percent Share for Rank 5 Ad in Test

Percent share of the top ranked ad from the total ad spend in the lift test.

(See description)

Sample Response as Parsed JSON.

{
    "last_updated_results": "2020-02-03",
    "id": "<STUDY_OBJECTIVE_ID>",
    "results": [
          {
           "cell_id":"245345342524524524",
            "experiment_id":"87668687789876",
            "population.test":23960325,
            "population.control":147985,
            "population.reached":22260305,
            "impressions":13212643,
            "frequency":4.2283423475836,
            "responders.test":468,
            "responders.control":455,
            "scoreSum.test":179,
            "scoreSum.control":156,
            "scoreSum.incremental":18.542345345142857,
            "scoreMean.test":0.3824244537863,
            "scoreMean.control":0.34285714245454,
            "scoreMean.incremental":0.03962234534562149,
            "breakthroughs.test":953130.363247862453,
            "breakthroughs.control":873448,
            "breakthroughs.incremental":96782.363237863,
            "breakthroughs.pValue":0.1706097872343,
            "costPerIncrementalBreakthrough":1.95992342316337,
            "spend":1958867.21,
            "costPerIncrementalBreakthroughRegion":0.33551658901041,
            "costPerIncrementalBreakthroughVertical":0.29259042385254,
            "scoreMeanRegion":0.086133689135313,
            "scoreMeanVertical":0.064593803137541,
            "isWinner.is_winner":0,
            "isWinner.confidence_level":-1,
            "breakthroughs.singleCellBayesianConfidence":0.88725,
            "advancedScoreSum.test":181.49706481615,
            "advancedScoreSum.control":156,
            "advancedScoreSum.incremental":20.686492128927,
            "advancedScoreMean.test":0.38781424106015,
            "advancedScoreMean.control":0.34361233480176,
            "advancedScoreMean.incremental":0.044201906258391,
            "advancedBreakthroughs.test":976667.50654348,
            "advancedBreakthroughs.control":865349.86784141,
            "advancedBreakthroughs.incremental":111317.63870207,
            "advancedBreakthroughs.informativeSingleCellBayesianConfidence":0.978,
            "advancedCostPerIncrementalBreakthrough":1.756839367779,
            "advancedBrandLiftCILower":0.0074638844331749,
            "advancedBrandLiftCIUpper":0.08074402106667,
            "advancedIsWinner.is_winner":null,
            "advancedIsWinner.confidence_level":null,
            "topNAdsId1":23844110090110745,
            "topNAdsSpendPercentage1":0.15010154182688,
            "topNAdsId2":23844149356200745,
            "topNAdsSpendPercentage2":0.076208506426327,
            "topNAdsId3":23844149352360745,
            "topNAdsSpendPercentage3":0.060832537356274,
            "topNAdsId4":23844162467120745,
            "topNAdsSpendPercentage4":0.058275732727315,
            "topNAdsId5":23844110087160745,
            "topNAdsSpendPercentage5":0.047210829806647
           }
    , ...]
}

Breakdown Results

You can get the highest-level breakdown by using the experiment_id parameter. For a more granular breakdown, you can retrieve the results by objective per experiment. You can also provide the breakdowns parameter.

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&breakdowns=['age']

BreakdownValues

Age

13–17, 18–24, 25–34, 35–44, 45–54, 55–54, 65+

Gender

M or F

The results return multiple JSON objects in the array based on the available breakdowns. For example, if age is provided, the results are broken down by age in the study.

You may provide one or more breakdowns; however, each combination of breakdowns must have at least 100 poll responses from the test and control groups combined for the results to show. Note that we only support age and gender breakdowns for studies that started after December 5, 2019.

{
  "id": "<STUDY_OBJECTIVE_ID>",
  "results": [
  {
    "age": "13-17",
    ...
    Default fields where the values are specific to the age='13-17' breakdown
    ...
  },
  {
    "age": "18-24",
    ...
    Default fields where the values are specific to the age='18-24' breakdown
    ...
  },
  ...],
}

{
  "id": "<STUDY_OBJECTIVE_ID>",
  "results": [
  {
    "age": "13-17",
    ...
    Default fields where the values are specific to the age='13-17' breakdown
    ...
  },
  {
    "age": "18-24",
    ...
    Default fields where the values are specific to the age='18-24' breakdown
    ...
  },
  ...],
}

Results for a Specific Date Stamp

You can specify a date stamp in your API call to obtain study results from a specific date. Note that the call returns the same result that it would if you made the same call on that specific date without including the date stamp field. The date should be within the prior 80 days.

curl -G \
      -d 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&ds=2020-03-01