{
  "openapi": "3.0.1",
  "info": {
    "title": "Audience export API",
    "description": "Use the Audience export REST API to access the output of an [audience export](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/audience-export.html) job.\n\nAfter an export job finishes running, its [output](https://doc.sitecore.com/cdp/en/users/sitecore-cdp/the-output-of-an-export.html) becomes available at presigned URLs. You can download the output of the export job by opening the URLs. The output is available for 35 days after creation.\n \n\nYou can access output URLs in two ways:\n   - Retrieve the output URLs for the most recently finished export job.\n   - 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.\n\nNote the following:\n   - To use this REST API, you must authorize your API requests.\n   - All API requests are made in your production environment. \n\n For more information, see the [official Sitecore CDP developer documentation](https://doc.sitecore.com/cdp/en/developers/api/index-en.html).\n\n# Authorization\nThe Audience export REST API uses the OAuth 2.0 standard with JSON web tokens to authorize REST API requests.\n### Create an API key\n  1. In the Sitecore Cloud Portal, open Sitecore CDP.\n  2. Click **Developer center** > **API keys** > **Create**.\n  3. Name your API key and select a feature. Then, click **Save**. The API key and the API secret display.\n  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.\n\n### Request an access token\nRun the following cURL command to request an access token. Replace the placeholder values with your API key and API secret.\n```curl\n  curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \\\n  --header 'Content-Type: application/x-www-form-urlencoded' \\\n  --data-urlencode 'client_id={YOUR_API_KEY}' \\\n  --data-urlencode 'client_secret={YOUR_API_SECRET}' \\\n  --data-urlencode 'grant_type=client_credentials' \\\n  --data-urlencode 'audience=https://api.sitecorecloud.io'\n```\nIn the response, the `access_token` key contains the access token:\n```json\n  {\n    \"access_token\": \"{YOUR_ACCESS_TOKEN}\",\n    \"scope\": \"cdp.audience_exports:r\",\n    \"expires_in\": 86400,\n    \"token_type\": \"Bearer\"\n  }\n```\nAccess 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.\n\nWe recommend that you cache the access token for 24 hours to avoid repeating this `POST` request while the access token is still valid.\n### Include the access token in the request header\nYou can now start making REST API requests. You must include the access token in the request header of every request. For example:\n\n  ```curl\n  curl -X GET '{YOUR_BASE_URL}/v2/...' \\\n  -H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \\\n  -H 'Accept: application/json'\n  ```\n",
    "contact": {
      "name": "Sitecore Corporation A/S"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "version": "v2",
    "x-metadata": {
      "product": "CDP"
    }
  },
  "security": [
    {
      "BearerToken": []
    }
  ],
  "servers": [
    {
      "url": "https://api-engage-ap.sitecorecloud.io",
      "description": "Production server AP"
    },
    {
      "url": "https://api-engage-eu.sitecorecloud.io",
      "description": "Production server EU"
    },
    {
      "url": "https://api-engage-jpe.sitecorecloud.io",
      "description": "Production server JP"
    },
    {
      "url": "https://api-engage-us.sitecorecloud.io",
      "description": "Production server US"
    }
  ],
  "tags": [
    {
      "name": "Most recent export job",
      "description": "Access output URLs for the most recently finished export job."
    },
    {
      "name": "Any export job",
      "description": "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."
    }
  ],
  "paths": {
    "/v2/audienceExports/definitions/{audienceExportRef}/reports": {
      "get": {
        "tags": [
          "Any export job"
        ],
        "summary": "Retrieve a list of all finished export jobs",
        "description": "Retrieves a list of all finished export jobs of an audience export.\n\nIn 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.",
        "operationId": "RetrieveFinishedExportJobs",
        "parameters": [
          {
            "name": "audienceExportRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The audience export reference.\nSet this value either to the friendly ID or the UUID reference of the audience export.\n\nTo 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/`.\n\nExample friendly ID: `daily_loyalty_members`\nExample UUID reference: `d6c5335a-4028-49c0-8d55-a534e89127c9` ",
              "example": "daily_loyalty_members"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExecutionReportName"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2/audienceExports/definitions/{audienceExportRef}/latestExport": {
      "get": {
        "tags": [
          "Most recent export job"
        ],
        "summary": "Retrieve output URLs for the most recent export job",
        "description": "Retrieves the presigned URLs where you can download the outputs of the most recently finished export job.\n\nIn the response, in every object in the `exports` array, the `url` key contains the output URL.\n\nThe 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.",
        "operationId": "RetrieveURLsOfMostRecentExportJob",
        "parameters": [
          {
            "name": "audienceExportRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The audience export reference.\nSet this value either to the friendly ID or the UUID reference of the audience export.\n\nTo 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/`.\n\nExample friendly ID: `daily_loyalty_members`\n\n Example UUID reference: `d6c5335a-4028-49c0-8d55-a534e89127c9` ",
              "example": "daily_loyalty_members"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportFileListingName"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2/audienceExports/executions/{jobExecutionRef}/export": {
      "get": {
        "tags": [
          "Any export job"
        ],
        "summary": "Retrieve output URLs for a specific export job",
        "description": "Retrieves the presigned URLs where you can download the outputs of the export job of your choice.\n\nIn the response, in every object in the `exports` array, the `url` key contains the output URL.\n\nThe 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.",
        "operationId": "RetrieveURLsOfSpecificExportJob",
        "parameters": [
          {
            "name": "jobExecutionRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The export job reference.\n\nIf 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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportFileListingName"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExecutionReportName": {
        "type": "object",
        "properties": {
          "clientKey": {
            "type": "string",
            "description": "Your organization's unique and public identifier.",
            "example": "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ"
          },
          "executionRef": {
            "type": "string",
            "description": "The export job reference.\n\nUse this as the `jobExecutionRef` path parameter when you retrieve output URLs for a specific export job.",
            "format": "uuid",
            "example": "fe351e84-3504-4668-8e5f-574d320b9679"
          },
          "definitionRef": {
            "type": "string",
            "description": "The UUID reference of the audience export.",
            "format": "uuid",
            "example": "d6c5335a-4028-49c0-8d55-a534e89127c9"
          },
          "friendlyId": {
            "type": "string",
            "description": "The unique ID of the audience export.\n\nOnly lowercase alphanumeric characters and underscores are allowed.",
            "example": "daily_loyalty_members"
          },
          "executionType": {
            "type": "string",
            "description": "Whether the audience export runs instantly or on a schedule.",
            "example": "INSTANT_RUN",
            "enum": [
              "INSTANT_RUN",
              "SCHEDULED"
            ]
          },
          "status": {
            "type": "string",
            "description": "The status of the export job.",
            "example": "SUCCESS",
            "enum": [
              "PENDING_GUEST_CONTEXT",
              "PENDING_SEGMENTATION",
              "PENDING_EMR_SUBMIT",
              "PENDING_EMR_JOB",
              "SUCCESS",
              "FAILED",
              "ALERT"
            ]
          },
          "definitionType": {
            "type": "string",
            "description": "Whether the audience export is a full or a delta export.",
            "example": "FULL_SYNC",
            "enum": [
              "DELTA",
              "FULL_SYNC"
            ]
          },
          "segmentExecutionType": {
            "type": "string",
            "description": "Whether the segment in the audience export is scheduled or live.",
            "example": "LIVE",
            "enum": [
              "ON_DEMAND",
              "LIVE"
            ]
          },
          "total": {
            "type": "integer",
            "description": "The number of guests in the segment selected for the export.",
            "format": "int32",
            "example": 101308
          },
          "filterMatchedGuests": {
            "type": "integer",
            "description": "The number of guests matched by the filter. These guests are included in the export. If no filter was used, the value is 0.",
            "format": "int32",
            "example": 97466
          },
          "filterNotMatchedGuests": {
            "type": "integer",
            "description": "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.",
            "format": "int32",
            "example": 3842
          },
          "filterFailures": {
            "type": "integer",
            "description": "The number of guests that filtering failed for. If no filter was used, the value is 0.",
            "format": "int32",
            "example": 16
          },
          "successes": {
            "type": "integer",
            "description": "The number of guests the export succeeded for.",
            "format": "int32",
            "example": 97466
          },
          "failures": {
            "type": "integer",
            "description": "The number of guests the export failed for.",
            "format": "int32",
            "example": 0
          },
          "programmableErrors": {
            "type": "array",
            "description": "A list of errors related to the JavaScript in the export and the attribute values in the output structure.",
            "items": {
              "$ref": "#/components/schemas/Errors"
            }
          },
          "filterErrors": {
            "type": "array",
            "description": "A list of errors related to conditions, for example, errors with the JavaScript in a condition.",
            "items": {
              "$ref": "#/components/schemas/Errors"
            }
          },
          "errorLogs": {
            "type": "array",
            "description": "A list of all errors.",
            "example": "[TypeError: Cannot read property 'length' of undefined]",
            "items": {
              "type": "string",
              "description": "A list of all errors.",
              "example": "[TypeError: Cannot read property 'length' of undefined]"
            }
          },
          "datasetDate": {
            "type": "string",
            "description": "The date the export job started running.",
            "example": "2024/10/16"
          },
          "startTime": {
            "type": "string",
            "description": "The UTC time the export job started running.",
            "format": "date-time",
            "example": "2024-10-16T06:00:01.122Z"
          },
          "endTime": {
            "type": "string",
            "description": "The UTC time the export job finished running.",
            "format": "date-time",
            "example": "2024-10-16T06:40:45.794Z"
          },
          "successAdd": {
            "type": "integer",
            "description": "Guests added to the segment after the export job ran. This attribute is only present in delta exports.",
            "format": "int32",
            "example": 0
          },
          "successRemove": {
            "type": "integer",
            "description": "Guests removed from the segment after the export job ran. This attribute is only present in delta exports.",
            "format": "int32",
            "example": 0
          }
        },
        "description": "ExecutionReportDescription"
      },
      "Errors": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Error description.",
            "example": "TypeError: Cannot read property 'length' of undefined"
          },
          "count": {
            "type": "integer",
            "description": "The number of times this error occurred.",
            "format": "int32",
            "example": 16
          }
        },
        "description": "A list of errors."
      },
      "BadRequestResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "The HTTP request status.",
            "format": "int32",
            "example": 400
          },
          "code": {
            "type": "integer",
            "description": "The HTTP response status code.",
            "format": "int32",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "example": "Bad request."
          },
          "developerMessage": {
            "type": "string",
            "description": "Error description for developers.",
            "example": "Attribute path param ref not a valid UUID."
          },
          "moreInfoUrl": {
            "type": "string",
            "description": "URL to get more information about the error.",
            "example": "Contact Sitecore support here: https://support.sitecore.com"
          }
        }
      },
      "UnauthorizedResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "The HTTP request status.",
            "format": "uppercase",
            "example": "UNAUTHORIZED"
          },
          "code": {
            "type": "integer",
            "description": "The HTTP response status code.",
            "format": "int32",
            "example": 401
          },
          "message": {
            "type": "string",
            "description": "Error description.",
            "example": "Authentication credentials are required to access the resource. All requests must be authenticated."
          },
          "moreInfoUrl": {
            "type": "string",
            "description": "URL to get more information about the error.",
            "example": "Contact Sitecore support here: https://support.sitecore.com"
          }
        }
      },
      "ExportFileListingName": {
        "type": "object",
        "properties": {
          "executionRef": {
            "type": "string",
            "description": "The export job reference.\n\nUse this as the `jobExecutionRef` path parameter when you retrieve output URLs for a specific export job.",
            "format": "uuid",
            "example": "fe351e84-3504-4668-8e5f-574d320b9679"
          },
          "definitionRef": {
            "type": "string",
            "description": "The UUID reference of the audience export.",
            "format": "uuid",
            "example": "d6c5335a-4028-49c0-8d55-a534e89127c9"
          },
          "friendlyId": {
            "type": "string",
            "description": "The unique ID of the audience export.\n\nOnly lowercase alphanumeric characters and underscores are allowed.",
            "example": "daily_loyalty_members"
          },
          "clientKey": {
            "type": "string",
            "description": "Your organization's unique and public identifier.",
            "example": "pqsPERS3lw12v5a9rrHPW1c4hET73GxQ"
          },
          "expireAt": {
            "type": "string",
            "description": "The UTC date and time the output URLs expire.",
            "format": "date-time",
            "example": "2024-11-05T12:08:00.145Z"
          },
          "numberOfFiles": {
            "type": "integer",
            "description": "The total number of files included in the output.",
            "format": "int32",
            "example": 2
          },
          "totalSizeKB": {
            "type": "integer",
            "description": "The total size of all the output files in kilobytes.",
            "format": "int64",
            "example": 54
          },
          "exports": {
            "type": "array",
            "description": "A list of all the presigned output URLs for the export job.",
            "items": {
              "$ref": "#/components/schemas/exports"
            }
          }
        },
        "description": "ExportFileListing"
      },
      "exports": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The presigned output URL for the export job.",
            "example": "https://sitecore-cdp-..."
          },
          "sizeKB": {
            "type": "integer",
            "description": "The size of the output file in kilobytes.",
            "format": "int64",
            "example": 52
          },
          "deltaAction": {
            "type": "string",
            "description": "Whether the presigned output URL of a delta export contains the added guests or the removed guests.\n\nThis attribute is only present in delta exports.",
            "example": "add",
            "enum": [
              "add",
              "remove"
            ]
          }
        },
        "description": "A list of all the presigned output URLs for the export job."
      }
    },
    "securitySchemes": {
      "BearerToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "x-logo": {
    "altText": "Audience export REST API",
    "url": "https://content-search-api-doc.rfksrv.com/logo.png"
  }
}