Sitecore API catalog
/
Sitecore CDP Audience export REST API
/
Any export job

Sitecore CDP Audience export REST API (v2)

Use the Audience export REST API to access the output of an audience export job.

After an export job finishes running, its output becomes available at presigned URLs. You can download the output of the export job by opening the URLs. You can access output URLs in two ways:

  • Retrieve the output URLs for the most recently finished export job.
  • First retrieve a list of all finished export jobs of the export, then retrieve the output URLs for any finished export job of your choice.

Note the following:

  • To use this REST API, you must authorize your API requests.
  • All API requests are made in your production environment.

For more information, see the official Sitecore CDP developer documentation.

Authorization

The Audience export REST API uses the OAuth 2.0 standard with JSON web tokens to authorize REST API requests.

Create an API key

  1. In the Sitecore Cloud Portal, open Sitecore CDP.
  2. Click Developer center > API keys > Create.
  3. Name your API key and select a feature. Then, click Save. The API key and the API secret display.
  4. Copy the API key and the API secret because you won't be able to view them again in Sitecore CDP. You'll use them to request an access token.

Request an access token

Run the following cURL command to request an access token. Replace the placeholder values with your API key and API secret.

  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_API_KEY}' \
  --data-urlencode 'client_secret={YOUR_API_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'

In the response, the access_token key contains the access token:

  {
    "access_token": "{YOUR_ACCESS_TOKEN}",
    "scope": "cdp.audience_exports:r",
    "expires_in": 86400,
    "token_type": "Bearer"
  }

Access tokens expire in 24 hours. If your requests unexpectedly return a response with status 401 Unauthorized, request a new access token by repeating this POST request.

We recommend that you cache the access token for 24 hours to avoid repeating this POST request while the access token is still valid.

Include the access token in the request header

You can now start making REST API requests. You must include the access token in the request header of every request. For example:

curl -X GET '{YOUR_BASE_URL}/v2/...' \
-H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
-H 'Accept: application/json'
Download OpenAPI description
index.json
index.yaml
Overview
License Apache 2.0
Languages
Servers
Production server AP
https://api-engage-ap.sitecorecloud.io/
Production server EU
https://api-engage-eu.sitecorecloud.io/
Production server JP
https://api-engage-jpe.sitecorecloud.io/
Production server US
https://api-engage-us.sitecorecloud.io/

Most recent export job

Access output URLs for the most recently finished export job.

Operations

Any export job

You can access output URLs for any finished export job by making two API requests. First retrieve a list of all finished export jobs of an audience export, then retrieve the output URLs for the finished export job of your choice.

Operations

Retrieve a list of all finished export jobs

Request

Retrieves a list of all finished export jobs of an audience export.

In the response, in every object in the array, the executionRef key contains the export job reference. You use the export job reference to retrieve the output URLs for that specific export job.

Path
audienceExportRefstringrequired

The audience export reference. Set this value either to the friendly ID or the UUID reference of the audience export.

To find these values in Sitecore CDP, click Audience export > Audience export, then the export you want to work with. The friendly ID is on the Details pane. The UUID reference is a 36-character string in the web browser's address bar, starting after audience-export/.

Example friendly ID: daily_loyalty_members Example UUID reference: d6c5335a-4028-49c0-8d55-a534e89127c9

Example: daily_loyalty_members
curl -i -X GET \
  'https://api-engage-ap.sitecorecloud.io/v2/audienceExports/definitions/{audienceExportRef}/reports' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful operation

Bodyapplication/jsonArray [
clientKeystring

Your organization's unique and public identifier.

Example: "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ"
executionRefstring(uuid)

The export job reference.

Use this as the jobExecutionRef path parameter when you retrieve output URLs for a specific export job.

Example: "fe351e84-3504-4668-8e5f-574d320b9679"
definitionRefstring(uuid)

The UUID reference of the audience export.

Example: "d6c5335a-4028-49c0-8d55-a534e89127c9"
friendlyIdstring

The unique ID of the audience export.

Only lowercase alphanumeric characters and underscores are allowed.

Example: "daily_loyalty_members"
executionTypestring

Whether the audience export runs instantly or on a schedule.

Enum"INSTANT_RUN""SCHEDULED"
Example: "INSTANT_RUN"
statusstring

The status of the export job.

Enum"PENDING_GUEST_CONTEXT""PENDING_SEGMENTATION""PENDING_EMR_SUBMIT""PENDING_EMR_JOB""SUCCESS""FAILED""ALERT"
Example: "SUCCESS"
definitionTypestring

Whether the audience export is a full or a delta export.

Enum"DELTA""FULL_SYNC"
Example: "FULL_SYNC"
segmentExecutionTypestring

Whether the segment in the audience export is scheduled or live.

Enum"ON_DEMAND""LIVE"
Example: "LIVE"
totalinteger(int32)

The number of guests in the segment selected for the export.

Example: 101308
filterMatchedGuestsinteger(int32)

The number of guests matched by the filter. These guests are included in the export. If no filter was used, the value is 0.

Example: 97466
filterNotMatchedGuestsinteger(int32)

The number of guests not matched by the filter. These guests are excluded from the export. If no filter was used, the value is 0.

Example: 3842
filterFailuresinteger(int32)

The number of guests that filtering failed for. If no filter was used, the value is 0.

Example: 16
successesinteger(int32)

The number of guests the export succeeded for.

Example: 97466
failuresinteger(int32)

The number of guests the export failed for.

Example: 0
programmableErrorsArray of objects(Errors)

A list of errors related to the JavaScript in the export and the attribute values in the output structure.

filterErrorsArray of objects(Errors)

A list of errors related to conditions, for example, errors with the JavaScript in a condition.

errorLogsArray of strings

A list of all errors.

Example: "[TypeError: Cannot read property 'length' of undefined]"
datasetDatestring

The date the export job started running.

Example: "2024/10/16"
startTimestring(date-time)

The UTC time the export job started running.

Example: "2024-10-16T06:00:01.122Z"
endTimestring(date-time)

The UTC time the export job finished running.

Example: "2024-10-16T06:40:45.794Z"
successAddinteger(int32)

Guests added to the segment after the export job ran. This attribute is only present in delta exports.

Example: 0
successRemoveinteger(int32)

Guests removed from the segment after the export job ran. This attribute is only present in delta exports.

Example: 0
]
Response
application/json
[
  {
    "clientKey": "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ",
    "executionRef": "fe351e84-3504-4668-8e5f-574d320b9679",
    "definitionRef": "d6c5335a-4028-49c0-8d55-a534e89127c9",
    "friendlyId": "daily_loyalty_members",
    "executionType": "INSTANT_RUN",
    "status": "SUCCESS",
    "definitionType": "FULL_SYNC",
    "segmentExecutionType": "LIVE",
    "total": 101308,
    "filterMatchedGuests": 97466,
    "filterNotMatchedGuests": 3842,
    "filterFailures": 16,
    "successes": 97466,
    "failures": 0,
    "programmableErrors": [ … ],
    "filterErrors": [ … ],
    "errorLogs": "[TypeError: Cannot read property 'length' of undefined]",
    "datasetDate": "2024/10/16",
    "startTime": "2024-10-16T06:00:01.122Z",
    "endTime": "2024-10-16T06:40:45.794Z",
    "successAdd": 0,
    "successRemove": 0
  }
]

Retrieve output URLs for a specific export job

Request

Retrieves the presigned URLs where you can download the outputs of the export job of your choice.

In the response, in every object in the exports array, the url key contains the output URL.

The URLs expire after a limited time. In the response, the expireAt key contains the expiration time. If you don't download the output before the URLs expire, you have to repeat this request to renew the URLs.

Path
jobExecutionRefstringrequired

The export job reference.

If you don't know the export job reference, first retrieve a list of all finished export jobs. In the response, the executionRef key contains the export job reference.

Example: fe351e84-3504-4668-8e5f-574d320b9679
curl -i -X GET \
  'https://api-engage-ap.sitecorecloud.io/v2/audienceExports/executions/{jobExecutionRef}/export' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful operation

Bodyapplication/json
executionRefstring(uuid)

The export job reference.

Use this as the jobExecutionRef path parameter when you retrieve output URLs for a specific export job.

Example: "fe351e84-3504-4668-8e5f-574d320b9679"
definitionRefstring(uuid)

The UUID reference of the audience export.

Example: "d6c5335a-4028-49c0-8d55-a534e89127c9"
friendlyIdstring

The unique ID of the audience export.

Only lowercase alphanumeric characters and underscores are allowed.

Example: "daily_loyalty_members"
clientKeystring

Your organization's unique and public identifier.

Example: "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ"
expireAtstring(date-time)

The UTC date and time the output URLs expire.

Example: "2024-11-05T12:08:00.145Z"
numberOfFilesinteger(int32)

The total number of files included in the output.

Example: 2
totalSizeKBinteger(int64)

The total size of all the output files in kilobytes.

Example: 54
exportsArray of objects(exports)

A list of all the presigned output URLs for the export job.

Response
application/json
{
  "executionRef": "fe351e84-3504-4668-8e5f-574d320b9679",
  "definitionRef": "d6c5335a-4028-49c0-8d55-a534e89127c9",
  "friendlyId": "daily_loyalty_members",
  "clientKey": "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ",
  "expireAt": "2024-11-05T12:08:00.145Z",
  "numberOfFiles": 2,
  "totalSizeKB": 54,
  "exports": [
    { … }
  ]
}