Create Predictions

This guide explains how to use mParticle Agent to choose a prediction type, create a Future Behavior prediction, interpret supported predictions, choose a target range, and prepare an audience from that range.

• Start with a business goal: Describe the behavior you want to predict. The agent can recommend Future Behavior, Similar Customers, or Best Offering.
• Review before creating: For a Future Behavior prediction, check the completed definition, Calculation Readiness, and pipeline capacity before approving creation.
• Choose who to target: For a Future Behavior prediction, the agent can recommend a target range based on the prediction’s results and your campaign goal. Review, adjust, and confirm the range in an interactive chart in the conversation.
• Build an audience: The agent prepares one individual audience from a Future Behavior or Similar Customers prediction for you to review and save. For a Future Behavior prediction, it uses the target range you confirm in the chart. For a Similar Customers prediction, provide the exact range you selected on the prediction details page.

For example, ask the agent to predict which customers will purchase footwear in the next 30 days or renew a subscription.

Supported prediction tasks

mParticle Agent can create Future Behavior predictions after you review and confirm a proposal. It cannot create Similar Customers or Best Offering predictions; you create those yourself in the manual Predictions workflow. The agent can recommend a prediction type, review saved configurations, and interpret current usable results for all three types.

The agent can use an active Future Behavior or Similar Customers prediction with current usable results to prepare one individual real-time audience. For a Future Behavior prediction, the agent can recommend a target range and show it in an interactive chart, where you review, adjust, and confirm it. For a Similar Customers prediction, you select the exact range on the prediction details page and provide it to the agent. In both cases, you review the audience proposal and confirm before the agent saves it. mParticle Agent cannot create an audience from a Best Offering prediction because that workflow requires a multi-node audience, which the agent does not currently support.

The steps below focus on creating a Future Behavior prediction with the agent. To create a Similar Customers or Best Offering prediction yourself, see Predictions Overview.

Before you begin

In order to use mParticle Agent to create a prediction:

• Predictions must be enabled for your account and the required setup must be complete.
• Your account must contain at least 45 days of historical data. For more reliable results, 90 or more days of data is recommended.

For more information, see Predictions setup requirements.

Each Future Behavior Prediction uses one pipeline, which is the processing capacity mParticle uses to calculate and refresh predictions. Your account must have enough available pipeline capacity to create it. For more information, see Predictions, pipelines, and predictive attributes.

Step 1: Open mParticle Agent

You can open mParticle Agent directly from the left-hand navigation by clicking mParticle Agent.

You can also open mParticle Agent from Predictions by clicking + New Predictive Attribute and selecting Build with mP Agent.

Step 2: Describe the behavior you want to predict

Start by describing the business outcome or future behavior you want to predict using plain language. You can start with a specific request, such as predict which customers will purchase footwear in the next 30 days, or an even broader goal, such as identify customers who are likely to renew their subscription.

You don’t need to know the exact event or attribute names. The agent reviews data tracked in your workspace, suggests a target behavior and filters, and asks questions when it needs more information. If it can’t find data that supports your request, it tells you what is missing.

To learn more about investigating available data using mParticle Agent before creating a prediction, see Explore Your Data.

Predictions are generally most useful for meaningful actions with sufficient historical behavioral data, such as purchases, subscriptions, upgrades, or repeat engagement.

Step 3: Review and refine the prediction definition

Review the definition to confirm that it represents the behavior and population you intend to predict. A Future Behavior Prediction definition includes:

• Predictive attribute name: The name of the attribute that the prediction will generate on user profiles.
• Prediction name: The name used to identify the saved prediction.
• Target behavior: The event whose future occurrence you want to predict.
• Event conditions: Optional filters that narrow the target behavior to a verified product, category, action subtype, or other supported event attribute value.
• Prediction window: How far into the future mParticle should predict whether a user will perform the target behavior.
• Users to evaluate: All users or a subset of users defined by supported criteria.
• Refresh schedule: When mParticle recalculates the prediction after its initial calculation.

If the definition doesn’t reflect your goal, reply to the agent with any feedback or corrections. For example, you could ask the agent to use a different event, add an event filter, change the prediction window, or narrow the users to evaluate.

The agent only uses events, attributes, and values found in your workspace. It won’t substitute a similarly named event that doesn’t represent the behavior you selected.

The prediction window is the period in which you want to know whether a user will perform the target behavior. It isn’t a reporting period.

Evaluating all users is supported, but a subset may better represent the relevant population for goals such as upgrades or sign-ups. Narrow the users to evaluate only when that matches the business goal and still leaves enough relevant data for the prediction to calculate reliably.

Step 4: Review Calculation Readiness and pipeline capacity

Before you create a Future Behavior prediction, mParticle Agent assesses the completed definition and shows its Calculation Readiness. This gives you a chance to review a potential calculation problem before creating the prediction.

• Checking: The assessment is in progress. Wait for a result before creating a proposal.
• Ready: Known calculation requirements appear to be met.
• At risk: The definition can proceed, but a condition may reduce the likelihood of a successful calculation. Review the reason before approving creation.
• Blocked: The prediction cannot proceed until you resolve the identified blocker.
• Unverified: Readiness could not be confirmed. Review the explanation before deciding whether to proceed.

In the following example, the completed definition displays the target behavior, users to evaluate, data environment, and refresh frequency.

The green Ready label in the top right of the definition card indicates that the completed definition appears likely to calculate. The details separately show that pipeline capacity is available.

In this At risk example, the agent warns that there may not be enough historical data to calculate the prediction successfully. You can improve the definition or continue to a proposal. Pipeline capacity is available, but it does not resolve the readiness concern.

Configuration completeness means all required inputs have been supplied. Calculation Readiness assesses whether that completed definition appears likely to calculate. Pipeline Capacity separately indicates whether a pipeline is available to create and calculate the prediction. A missing required input leaves the definition incomplete; it is not an At risk result. See Pipeline usage and limits for more information.

A Ready assessment does not guarantee a successful calculation, final Strength, or campaign results. If your account does not have an available pipeline, review your existing predictions in Customer 360 > Predictive Attributes or contact your mParticle account representative.

Step 5: Review the proposal and create the prediction

Before approving the proposal, confirm:

• Target behavior and conditions: The selected event and filters represent the action you want to predict.
• Predictive attribute and window: The attribute name and prediction window match the intended use.
• Prediction name and refresh schedule: The saved name and schedule match your intended workflow.
• Users to evaluate: The selected users represent the population relevant to your goal.
• Calculation Readiness: You have reviewed the result and its explanation and improved the definition if needed.
• Pipeline capacity: Your account has enough capacity to create the prediction.

Nothing is created until you explicitly approve the proposal. After you approve it, the agent creates the Future Behavior Prediction using the reviewed configuration.

Step 6: Review results and choose a target range

After the prediction is Active and has current usable results, ask mParticle Agent about it by name. For example, ask how is my footwear purchase prediction performing? or help me choose who to target with my footwear purchase prediction. The agent can explain the prediction’s status, last refresh, refresh frequency, Strength, and other quality information.

A prediction’s Strength indicates how well it identifies users who are more likely to perform the target behavior. It isn’t an individual user’s probability of conversion or a guarantee of campaign performance. Interpret Strength in the context of your campaign, as explained in Manage Future Behavior Predictions.

Other quality metrics describe how well the prediction performs overall. They don’t show an individual user’s chance of acting.

Get a target range recommendation

Tell the agent what you want the campaign to achieve. For example, you might want to focus on the users most likely to convert, balance reach and efficiency, or reach a broader population. Include any budget or reach constraints. If you described your goal when you created the prediction with the agent, it uses that goal and tells you so. If your goal would change the recommendation and you haven’t stated it, the agent asks one question about it.

The agent then recommends a target range based on the prediction’s current results:

• How predicted likelihood changes across users, ranked from least to most likely to perform the target behavior
• The prediction’s average predicted likelihood
• The estimated number of users and predicted conversion rate (CVR) of different ranges

The agent looks for meaningful drops in predicted likelihood, or the point where expanding the range adds reach but less value, instead of defaulting to a fixed cutoff such as the top 10%. It doesn’t recommend targeting all users as the best use of a prediction. With each recommendation, the agent briefly explains the tradeoff between reach and predicted conversion. If you change your goal, the agent reassesses its recommendation.

For a prediction of a negative outcome, such as churn, higher predicted likelihood indicates greater risk, not a better customer outcome. The agent takes the direction of the outcome into account when it recommends a range.

Review and adjust the range in the chart

The agent shows its recommendation in an interactive chart in the conversation, with the recommended range already selected. The chart is labeled with the prediction’s name and includes:

• Target percentile range: A slider that runs from Least Likely (0.0) to Most Likely (1.0), with fields that show the start and end of the selected range.

• Selected Range Results: Estimates for the users the prediction scored within the selected range:

  • Number of Users: The estimated number of scored users in the range, and what share of all scored users that represents. For example, Top 18% of total ~535.1k users scored.
  • Predicted CVR: The predicted conversion rate of users in the range, and its lift compared with the prediction’s average. For example, 1.7x lift compared to average.
• Predicted CVR chart: Scored users divided into equally sized groups by likelihood percentile. For each group, the chart shows its predicted conversion rate and its Predicted Lift compared with the average, which appears as a dotted line. The selected range is highlighted.

To compare options, drag the slider handles or enter the start and end of the range in the fields. The Selected Range Results and highlighted area update for the range you select. Look at how predicted CVR changes across groups: in this example, predicted CVR stays close to the average until about the 0.8 percentile, then rises sharply.

To accept the recommended range as shown, click Confirm Range, or Apply Range when the range is for an audience you’re building. If you adjusted the selection, click Use Selected Range, which is available only after you change the range. You can also tell the agent to apply a range it showed you.

After you use a range, its chart becomes read-only. To choose a different range, ask the agent, and it shows the new range in a new chart.

The chart’s estimates are modeled from the prediction’s results. They aren’t observed campaign outcomes, and the Number of Users isn’t the size of an audience built from the range. Additional criteria may change the final audience size.

Ask for a specific range

You can also type the range you want, such as use the top 15% or target the 85th through 100th percentile. The agent shows that exact range in the chart so you can review its estimates. The range isn’t applied until you confirm it.

The chart can also refer to named ranges:

• Most likely users: Users in the 90th through 100th percentile. If you ask for “the most likely users” in conversation, the agent confirms that you mean this range before using it. A request for the top 10% uses this range without another question.
• Users above average: Users whose predicted likelihood is above the prediction’s average. This isn’t the same as the top half of users, and the boundary can change between predictions and between calculations of the same prediction.

Similar Customers predictions

The agent doesn’t recommend target ranges or show the chart for Similar Customers predictions. Select the range on the prediction’s details page in Customer 360 > Predictive Attributes, then provide the exact range to the agent. The agent uses that range for audience creation without changing it.

For more information about Strength, results, and target ranges, see Manage Future Behavior Predictions.

Step 7: Prepare an audience from the prediction

Before asking the agent to prepare an audience, confirm:

• The prediction is Active and has current usable results.
• You reviewed the prediction’s Strength and other quality information.
• You confirmed a target range in the chart or, for a Similar Customers prediction, provided the exact range you selected on the prediction details page.

If you’ve asked for an audience, the agent continues to the audience definition after you confirm a range, without asking you to approve the range again. When it prepares the audience, it uses:

• The completed prediction and its predictive attribute.
• The confirmed target range.
• Any business context and additional audience requirements you provide.

The audience uses the prediction and selected range as one condition. You can also ask the agent to add verified audience requirements, such as geography, consent or channel eligibility, or excluding current customers. These requirements don’t change the prediction’s target behavior, prediction window, or users to evaluate.

The agent keeps your selected percentile range unchanged. When mParticle stores percentiles as decimals, the agent converts the equivalent range automatically (for example, the 85th through 100th percentile becomes 0.85 through 1.00).

Change the range of a draft audience

To change the target range of an audience you’re still building, ask the agent, for example change this audience to the top 20%. The agent shows the new range in the chart and leaves the current definition unchanged until you click Apply Range or, after adjusting the selection, Use Selected Range, or tell it to apply the range. It then replaces only the prediction condition, keeps your other criteria and exclusions, and shows the revised definition with an updated size estimate.

The audience’s estimated size can differ from the chart’s Number of Users, even when the prediction range is the only condition. The chart estimates how many scored users fall in the range, while the audience estimate is calculated separately for the complete audience definition.

In the following example, the audience uses the Likely Repeat Purchasers - 30 Days prediction as its only condition. The audience card shows the prediction range in the Audience Definition and its own Estimated Size, which can differ from the chart’s Number of Users for the same range.

Review and save the audience

Confirming a range never saves an audience. Review the resulting audience definition and proposal before saving it. The agent can prepare one real-time audience, but it can’t create a more complex audience group, parent or child audiences, A/B splits, or remaining users audiences.

After saving the audience, connect it to an output and activate it in the mParticle UI. The agent doesn’t perform these steps. For more information about reviewing and saving audiences with the agent, see Build Audiences.

The audience remains linked to the predictive attribute. As the prediction refreshes, audience membership updates according to the selected range and any additional requirements. Monitor campaign performance against your usual benchmarks or control group, and periodically check that the prediction remains Active and refreshes as expected.

Troubleshooting prediction creation issues

The agent says my workspace isn’t ready to create a prediction

Confirm that Predictions has been set up for your account and that you have at least 45 days of usable historical data. Events visible elsewhere in mParticle aren’t necessarily ready for Predictions. For more information, see Predictions setup requirements.

If the agent can’t retrieve the applicable state, treat the prerequisite as unverified rather than missing. Contact your mParticle account representative for help confirming availability and setup.

The definition includes a warning

Review the agent’s explanation. You may need to select a target behavior that occurs more frequently, broaden the users to evaluate, or revise filters that leave too little usable data. Ask the agent to evaluate the revised definition before creating the prediction.

The account doesn’t have an available pipeline

A Future Behavior Prediction requires one pipeline to calculate. Review your current pipeline usage and existing predictions. To free capacity, you can delete an unused prediction after removing it from any audiences that reference it. For instructions, see View and Manage Predictions. Otherwise, contact your mParticle account representative to discuss your account’s pipeline capacity.

The prediction is still calculating

New predictions can take up to 24 hours to calculate. Wait until the prediction completes successfully and results become available before asking the agent to interpret results, recommend a target range, or prepare an audience.

The agent can’t hand a prediction off to audience creation until mParticle shows that the prediction is Active and usable. Predictions that are Calculating, Inactive, or Failed aren’t ready for this handoff.

The agent doesn’t show a chart for my prediction

The agent recommends target ranges and shows the interactive chart only for Future Behavior predictions that are Active and have current usable results. It doesn’t recommend ranges for Similar Customers or Best Offering predictions.

The audience estimate doesn’t match the chart’s Number of Users

The chart’s Number of Users counts the users the prediction scored within the range. The audience size estimate is calculated separately for the complete audience definition, including any other criteria and exclusions. The two numbers can differ even when the prediction range is the audience’s only condition. Use the audience estimate to judge the size of the audience you’re saving.

The agent says the prediction type isn’t supported

mParticle Agent creates Future Behavior predictions. Use the Predictive Attributes page to create Similar Customers or Best Offering predictions.

Next steps

• Build Audiences: Learn how to review and save the audience prepared from a prediction.
• Future Behavior Predictions Overview: Learn how Future Behavior Predictions work and when to use them.
• View and Manage Predictions: Monitor prediction status, Strength, and refresh frequency.