Previews and estimates endpoints
As you develop a segment definition, you can use the estimate and preview tools within Adobe Experience Platform to view summary-level information to help ensure that you are isolating the audience you expect.
-
Previews provide paginated lists of qualifying profiles for a segment definition, allowing you to compare the results against what you expect.
-
Estimates provide statistical information on a segment definition, such as the projected audience size, confidence interval, and error standard deviation.
Getting started
The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.
How estimates are generated
When the ingestion of records into the Profile store increases or decreases the total profile count by more than 5%, a sampling job is triggered to update the count. The way data sampling is triggered depends on the method of ingestion:
- Batch ingestion: For batch ingestion, within 15 minutes of successfully ingesting a batch into the Profile store, if the 5% increase or decrease threshold is met, a job is run to update the count.
- Streaming ingestion: For streaming data workflows, a check is done on an hourly basis to determine if the 5% increase or decrease threshold has been met. If it has, a job is automatically triggered to update the count.
The sample size of the scan depends on the overall number of entities in your profile store. These sample sizes are represented in the following table:
Create a new preview create-preview
You can create a new preview by making a POST request to the /preview endpoint.
API format
POST /preview
Request
curl -X POST https://platform.adobe.io/data/core/ups/preview \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '
{
"predicateExpression": "xEvent.metrics.commerce.abandons.value > 0",
"predicateType": "pql/text",
"predicateModel": "_xdm.context.profile",
"graphType": "none"
}'
predicateExpressionpredicateTypepredicateExpression. Currently, the only accepted value for this property is pql/text.predicateModelgraphTypenone (performs no identity stitching) and pdg (performs identity stitching based on your private identity graph).Response
A successful response returns HTTP status 201 (Created) with details of your newly created preview.
{
"state": "NEW",
"previewQueryId": "e890068b-f5ca-4a8f-a6b5-af87ff0caac3",
"previewQueryStatus": "NEW",
"previewId": "MDphcHAtMzJiZTAzMjgtM2YzMS00YjY0LThkODQtYWNkMGM0ZmJkYWQzOmU4OTAwNjhiLWY1Y2EtNGE4Zi1hNmI1LWFmODdmZjBjYWFjMzow",
"previewExecutionId": 0
}
statepreviewIdRetrieve the results of a specific preview get-preview
You can retrieve detailed information about a specific preview by making a GET request to the /preview endpoint and providing the preview ID in the request path.
API format
GET /preview/{PREVIEW_ID}
{PREVIEW_ID}previewId value of the preview you want to retrieve.Request
curl -X GET https://platform.adobe.io/data/core/ups/preview/MDphcHAtMzJiZTAzMjgtM2YzMS00YjY0LThkODQtYWNkMGM0ZmJkYWQzOmU4OTAwNjhiLWY1Y2EtNGE4Zi1hNmI1LWFmODdmZjBjYWFjMzow \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with detailed information about the specified preview.
{
"results": [{
"XID_ADOBE-MARKETING-CLOUD-ID-1": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_ADOBE-MARKETING-CLOUD-ID-1",
"endCustomerIds": {
"XID_COOKIE_ID_1": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE_ID_1"
},
"XID_PROFILE_ID_1": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_PROFILE_ID_1"
}
}
}
},
{
"XID_COOKIE-ID-2": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE-ID-2",
"endCustomerIds": {
"XID_COOKIE_ID_2-1": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_COOKIE_ID_2-1"
},
"XID_PROFILE_ID_2": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_PROFILE_ID_2"
}
}
},
"XID_ADOBE-MARKETING-CLOUD-ID-3": {
"_href": "https://platform.adobe.io/data/core/ups/models/profile/XID_ADOBE-MARKETING-CLOUD-ID-1000"
}
}],
"state": "RESULT_READY",
"links": {
"_self": "https://platform.adobe.io/data/core/ups/preview?expression=<expr-1>&limit=1000",
"next": "",
"prev": ""
},
"page": {
"offset": 0,
"size": 3
}
}
resultsRetrieve the results of a specific estimate job get-estimate
Once you have created a preview job, you can use its previewId in the path of a GET request to the /estimate endpoint to view statistical information about the segment definition, including projected audience size, confidence interval, and error standard deviation.
API format
GET /estimate/{PREVIEW_ID}
{PREVIEW_ID}previewId value returned when the preview job was created.Request
The following request retrieves the results of a specific estimate job.
curl -X GET https://platform.adobe.io/data/core/ups/estimate/MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with details of the estimate job.
{
"estimatedSize": 4275,
"numRowsToRead": 4275,
"estimatedNamespaceDistribution": [
{
"namespaceId": "4",
"profilesMatchedSoFar": 35
},
{
"namespaceId": "6",
"profilesMatchedSoFar": 4275
}
],
"state": "RESULT_READY",
"profilesReadSoFar": 4275,
"standardError": 0,
"error": {
"description": "",
"traceback": ""
},
"profilesMatchedSoFar": 4275,
"totalRows": 4275,
"confidenceInterval": "95%",
"_links": {
"preview": "https://platform.adobe.io/data/core/ups/preview/app-32be0328-3f31-4b64-8d84-acd0c4fbdad3/execution/0?previewQueryId=e890068b-f5ca-4a8f-a6b5-af87ff0caac3"
}
}
estimatedNamespaceDistributionstate_links.previewstate is “RESULT_READY”, this field provides a URL to view the estimate.Next steps
After reading this guide you should have a better understanding of how to work with previews and estimates using the Segmentation API. To learn how to access metrics related to your Real-Time Customer Profile data, such as the total number of profile fragments and merged profiles within specific namespaces or the Profile data store as a whole, please visit the profile preview (/previewsamplestatus) endpoint guide.