openapi: 3.2.0 info: title: Segmentation Service Segment jobs API description: "\nAdobe Experience Platform Segmentation Service provides a user interface and RESTful API that allows you to create audiences through segment definitions or other sources from your Real-Time Customer Profile data. These audiences are centrally configured and maintained on Platform, and are readily accessible by any Adobe solution. Use the Segmentation Service API to programmatically integrate the service's various functionalities into your experience application, providing RESTful endpoints for managing audiences, segment definitions, segment jobs, exports, schedules, and more.\n- **Related documentation**:\n - [Segmentation Service documentation](https://www.adobe.com/go/segmentation-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n - [Segmentation Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Segmentation%20Service%20API.postman_collection.json)\n - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n - [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- **API paths**: \n - PLATFORM Gateway URL: https://platform.adobe.io/\n - Base path for this API: /data/core/ups\n - Example of a complete path: https://platform.adobe.io/data/core/ups/segment/definitions\n\n- **Required headers**:\n - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](https://www.adobe.com/go/platform-api-authentication-en).\n - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \\\"prod\\\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en)for more information. \n - All requests with a payload in the request body(such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)." version: '1.0' servers: - url: //{environment}.adobe.io/data/core/ups variables: environment: default: platform enum: - platform - platform-stage tags: - name: Segment jobs description: Segment jobs process previously established segment definitions to generate an audience. More information about using this set of endpoints can be found in the [segment jobs endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/segmentation/api/segment-jobs.html). paths: /segment/jobs: get: tags: - Segment jobs summary: List all segment job requests operationId: listSegmentJobs parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/x-api-key' - $ref: '#/components/parameters/x-gw-ims-org-id' - $ref: '#/components/parameters/x-sandbox-name' - name: x-request-id in: header description: A unique ID that can be used to track a request. schema: type: string example: q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA - name: snapshot.name in: query description: The snapshot name. schema: type: string example: inUS - name: start in: query description: The page offset, as per the created time of the resource. schema: type: integer format: int64 example: 2 - name: limit in: query description: The maximum number of segment jobs retrieved per page. schema: type: integer example: 10 - name: status in: query description: The job status. schema: type: string example: PROCESSING - name: sort in: query description: Used to order the segment jobs. Is written in the format [attributeName]:[desc|asc] schema: type: string example: creationTime:desc - name: property in: query description: Used to get exact matches within an attribute in the segment job. Is written in the format [arrayTypeAttributeName]~[objectKey]==[value] schema: type: string example: segments~segmentId==workInCanada responses: 200: x-summary: Success description: A list of the segment jobs returned. content: application/json: schema: $ref: '#/components/schemas/ListSegmentJobs' example: _page: totalCount: 14 pageSize: 14 children: - id: 468eeefd-95a2-45a1-8bfc-b806dafce7ee imsOrgId: E95186D65A28ABF00A495D82@AdobeOrg sandbox: sandboxId: 28e74200-e3de-11e9-8f5d-7f27416c5f0d sandboxName: prod type: production default: true profileInstanceId: ups source: scheduler status: PROCESSING batchId: 65e18145-a5e8-4993-94f3-c70fadaa1fef computeJobId: 11037 computeGatewayJobId: 9ea97b25-a0f5-410e-ae87-b2d85e58f399 segments: - segmentId: 30230300-ccf1-48ad-8012-c5563a007069 segment: id: 30230300-ccf1-48ad-8012-c5563a007069 expression: type: PQL format: pql/text value: workAddress.country = "US" mergePolicyId: 25c548a0-ca7f-4dcd-81d5-997642f178b9 mergePolicy: id: 25c548a0-ca7f-4dcd-81d5-997642f178b9 version: 1 metrics: totalTime: startTimeInMs: 1573203617195 endTimeInMs: 1573204395655 totalTimeInMs: 778460 profileSegmentationTime: startTimeInMs: 1573204266727 endTimeInMs: 1573204395655 totalTimeInMs: 128928 totalProfiles: 13146432 segmentedProfileCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: 1033 segmentedProfileByNamespaceCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: tenantiduserobjid: 1033 campaign_profile_mscom_mkt_prod2: 1033 segmentedProfileByStatusCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: exited: 144646 existing: 10 realized: 2056 totalProfilesByMergePolicy: 25c548a0-ca7f-4dcd-81d5-997642f178b9: 13146432 requestId: 4e538382-dbd8-449e-988a-4ac639ebe72b-1573203600264 schema: name: _xdm.context.profile properties: scheduleId: 4e538382-dbd8-449e-988a-4ac639ebe72b runId: e6c1308d-0d4b-4246-b2eb-43697b50a149 _links: cancel: href: /segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f method: DELETE checkStatus: href: /segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f method: GET updateTime: 1573204395000 creationTime: 1573203600535 updateEpoch: 1573204395 403: x-summary: Missing access permissions description: Access is forbidden. content: {} 500: x-summary: Internal server error description: There was an issue reading the segment job. content: {} 503: x-summary: Service unavailable description: The service is unavailable. content: {} post: tags: - Segment jobs summary: Create a segment job request operationId: createSegmentJob parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/content-type' - $ref: '#/components/parameters/x-api-key' - $ref: '#/components/parameters/x-gw-ims-org-id' - $ref: '#/components/parameters/x-sandbox-name' - name: x-profile-instance-id in: header description: 'The ID of the Profile Instance. **Example**: `ups`' schema: type: string example: ups - name: x-request-id in: header description: 'A unique ID that can be used to track a request. **Example**: `q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA`' schema: type: string example: q0gf6caRuRtX2s5khaN1Zgd1OoEXcPJA requestBody: description: List of segment jobs. Each should be in JSON format. content: application/json: schema: type: array items: $ref: '#/components/schemas/SegmentJobRequest' example: - segmentId: 4afe34ae-8c98-4513-8a1d-67ccaa54bc05 required: true responses: 200: x-summary: Success description: The segment job request was successfully posted. content: application/json: schema: $ref: '#/components/schemas/SegmentJob' 400: x-summary: Error description: The segment job request could not be posted. Double check your request body content. content: {} 403: x-summary: Missing access permissions description: Access is forbidden. content: {} 429: x-summary: Rate limit description: There are too many segmentation jobs in processing at the moment. Try again at a later time. content: {} 500: x-summary: Internal service error description: There was an issue reading the segment job. content: {} 503: x-summary: Service unavailable description: The service is unavailable. content: {} x-codegen-request-body-name: body /segment/jobs/{SEGMENT_JOB_ID}: get: tags: - Segment jobs summary: Retrieve a segment job request operationId: retrieveSegmentJob parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/x-api-key' - $ref: '#/components/parameters/x-gw-ims-org-id' - $ref: '#/components/parameters/x-sandbox-name' - name: SEGMENT_JOB_ID in: path description: The ID of the segment job request. required: true schema: type: string - name: x-request-id in: header description: An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request. schema: type: string responses: 200: x-summary: Success description: The segment job request was successfully retrieved. content: application/json: schema: $ref: '#/components/schemas/SegmentJob' example: id: 468eeefd-95a2-45a1-8bfc-b806dafce7ee imsOrgId: E95186D65A28ABF00A495D82@AdobeOrg sandbox: sandboxId: 28e74200-e3de-11e9-8f5d-7f27416c5f0d sandboxName: prod type: production default: true profileInstanceId: ups source: scheduler status: PROCESSING batchId: 65e18145-a5e8-4993-94f3-c70fadaa1fef computeJobId: 11037 computeGatewayJobId: 9ea97b25-a0f5-410e-ae87-b2d85e58f399 segments: - segmentId: 30230300-ccf1-48ad-8012-c5563a007069 segment: id: 30230300-ccf1-48ad-8012-c5563a007069 expression: type: PQL format: pql/text value: workAddress.country = "US" mergePolicyId: 25c548a0-ca7f-4dcd-81d5-997642f178b9 mergePolicy: id: 25c548a0-ca7f-4dcd-81d5-997642f178b9 version: 1 metrics: totalTime: startTimeInMs: 1573203617195 endTimeInMs: 1573204395655 totalTimeInMs: 778460 profileSegmentationTime: startTimeInMs: 1573204266727 endTimeInMs: 1573204395655 totalTimeInMs: 128928 totalProfiles: 13146432 segmentedProfileCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: 1033 segmentedProfileByNamespaceCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: tenantiduserobjid: 1033 campaign_profile_mscom_mkt_prod2: 1033 segmentedProfileByStatusCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: exited: 144646 existing: 10 realized: 2056 totalProfilesByMergePolicy: 25c548a0-ca7f-4dcd-81d5-997642f178b9: 13146432 requestId: 4e538382-dbd8-449e-988a-4ac639ebe72b-1573203600264 schema: name: _xdm.context.profile properties: scheduleId: 4e538382-dbd8-449e-988a-4ac639ebe72b runId: e6c1308d-0d4b-4246-b2eb-43697b50a149 _links: cancel: href: /segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f method: DELETE checkStatus: href: /segment/jobs/b31aed3d-b3b1-4613-98c6-7d3846e8d48f method: GET updateTime: 1573204395000 creationTime: 1573203600535 updateEpoch: 1573204395 403: x-summary: Missing access permissions description: Access is forbidden. content: {} 404: x-summary: Not found description: The segment job request was not found. content: {} 503: x-summary: Service unavailable description: The service is unavailable. content: {} delete: tags: - Segment jobs summary: Cancel a segment job request operationId: deleteSegmentJob parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/x-api-key' - $ref: '#/components/parameters/x-gw-ims-org-id' - $ref: '#/components/parameters/x-sandbox-name' - name: SEGMENT_JOB_ID in: path description: The ID of the segment job request. required: true schema: type: string - name: x-request-id in: header description: An optional header that may be used for debugging purposes when investigating issues with a workflow. The same ID can be used to identify a single request to the service from a flow. A new ID should be created for each request. schema: type: string responses: 204: x-summary: Success description: The segment job request has been marked for cancellation. content: {} 403: x-summary: Missing access permissions description: Access is forbidden. content: {} 404: x-summary: Not found description: The segment job request was not found. content: {} 503: x-summary: Service unavailable description: The service is unavailable. content: {} /segment/jobs/bulk-get: post: tags: - Segment jobs summary: Retrieve multiple segment jobs using multiple job IDs operationId: bulkGetSegmentJobs parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/content-type' - $ref: '#/components/parameters/x-api-key' - $ref: '#/components/parameters/x-gw-ims-org-id' - $ref: '#/components/parameters/x-sandbox-name' requestBody: description: An array of the segment jobs IDs that you are trying to retrieve. content: application/json: schema: type: object properties: ids: type: array items: type: object properties: id: type: string example: cc3419d3-0389-47f1-b174-fead6b3c830d example: ids: - id: cc3419d3-0389-47f1-b174-fead6b3c830d - id: c527dc3f-07fe-4b96-be4e-23f38e734ff8 required: true responses: 207: x-summary: Success description: The details of each segment jobs is returned. content: application/json: schema: $ref: '#/components/schemas/BulkGetSegmentJobs' example: results: cc3419d3-0389-47f1-b174-fead6b3c830d: id: cc3419d3-0389-47f1-b174-fead6b3c830d imsOrgId: E95186D65A28ABF00A495D82@AdobeOrg sandbox: sandboxId: 28e74200-e3de-11e9-8f5d-7f27416c5f0d sandboxName: prod type: production default: true profileInstanceId: ups status: PROCESSING batchId: 651fc109-3963-48d2-aa98-9e3cc2003bac computeJobId: 39312 computeGatewayJobId: a0099ab6-11ab-4c2b-a0ea-6162e16806bd segments: - segmentId: cc3419d3-0389-47f1-b174-fead6b3c830d segment: null id: cc3419d3-0389-47f1-b174-fead6b3c830d, expression: type: PQL format: pql/text value: workAddress.country = "US" mergePolicyId: 25c548a0-ca7f-4dcd-81d5-997642f178b9 mergePolicy: id: 25c548a0-ca7f-4dcd-81d5-997642f178b9, version: 1 metrics: totalTime: startTimeInMs: 1573203617195 endTimeInMs: 1573204395655 totalTimeInMs: 778460 profileSegmentationTime: startTimeInMs: 1573204266727 endTimeInMs: 1573204395655 totalTimeInMs: 128928 totalProfiles: 13146432 segmentedProfileCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: 1033 segmentedProfileByNamespaceCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: tenantiduserobjid: 1033 campaign_profile_mscom_mkt_prod2: 1033 segmentedProfileByStatusCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: exited: 144646 existing: 10 realized: 2056 totalProfilesByMergePolicy: 25c548a0-ca7f-4dcd-81d5-997642f178b9: 13146432 updateTime: 1573204395000 creationTime: 1573203600535 c527dc3f-07fe-4b96-be4e-23f38e734ff8: id: c527dc3f-07fe-4b96-be4e-23f38e734ff8 imsOrgId: E95186D65A28ABF00A495D82@AdobeOrg sandbox: sandboxId: 28e74200-e3de-11e9-8f5d-7f27416c5f0d sandboxName: prod type: production default: true status: SUCCEEDED segments: - segmentId: c527dc3f-07fe-4b96-be4e-23f38e734ff8 segment: id: c527dc3f-07fe-4b96-be4e-23f38e734ff8 expression: type: PQL format: pql/text value: workAddress.country = "US" mergePolicyId: 25c548a0-ca7f-4dcd-81d5-997642f178b9 mergePolicy: id: 25c548a0-ca7f-4dcd-81d5-997642f178b9 version: 1 metrics: totalTime: startTimeInMs: 1573203617195 endTimeInMs: 1573204395655 totalTimeInMs: 778460 profileSegmentationTime: startTimeInMs: 1573204266727 endTimeInMs: 1573204395655 totalTimeInMs: 128928 totalProfiles: 13146432 segmentedProfileCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: 1033 segmentedProfileByNamespaceCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: tenantiduserobjid: 1033 campaign_profile_mscom_mkt_prod2: 1033 segmentedProfileByStatusCounter: 94509dba-7387-452f-addc-5d8d979f6ae8: exited: 144646 existing: 10 realized: 2056 totalProfilesByMergePolicy: 25c548a0-ca7f-4dcd-81d5-997642f178b9: 13146432 updateTime: 1573204395000 creationTime: 1573203600535 x-codegen-request-body-name: body components: schemas: BulkGetSegmentJobs: type: object properties: results: type: object SegmentJobRequest: required: - segmentId type: object properties: segmentId: type: string description: The ID of the segment definition. example: 7863c010-e092-41c8-ae5e-9e533186752e SegmentJobErrorResponse: type: object properties: code: type: string description: The error code for the segment job. example: 8.0000018E7 msg: type: string description: The segment job error message. example: 'com.microsoft.azure.documentdb.DocumentClientException: Message: {"Errors":["Request rate is large"]}' callStack: type: string description: Call stack description: The error response from the segment job. SegmentInfo: required: - segment type: object properties: segmentId: type: string description: The segment definition ID. example: 7863c010-e092-41c8-ae5e-9e533186752e segment: required: - expression - mergePolicy type: object properties: id: type: string description: The segment definition ID. example: 7863c010-e092-41c8-ae5e-9e533186752e version: type: integer description: The segment definition version. format: int32 example: 1 expression: $ref: '#/components/schemas/Expression' mergePolicyId: type: string example: 25c548a0-ca7f-4dcd-81d5-997642f178b9 mergePolicy: type: object properties: id: type: string description: The ID of the merge policy. example: ups-default version: type: integer description: The version of the merge policy. format: int32 example: 1 description: Merge policy information for the segment definition. description: The metadata for the segment definitions. description: The segment definitions returned within a segment job. Expression: type: object properties: type: type: string description: The type of the expression. example: PQL enum: - PQL - ARL format: type: string description: The format of the expression. example: pql/text enum: - pql/text - pql/json value: type: string description: The query string, written as PQL. example: workAddress.country = "US" description: Information regarding the segment definition's expression. ListSegmentJobs: type: object properties: _page: type: object properties: totalCount: type: integer pageSize: type: integer children: type: array description: An object containing the request segment jobs. items: $ref: '#/components/schemas/SegmentJob' SegmentJob: required: - metrics - segments type: object properties: id: type: string description: The segment job request ID. example: 468eeefd-95a2-45a1-8bfc-b806dafce7ee imsOrgId: type: string description: The organization ID that was provided. example: '{IMG_ORG}' sandbox: type: object properties: sandboxId: type: string example: 28e74200-e3de-11e9-8f5d-7f27416c5f0d sandboxName: type: string example: prod type: type: string example: production default: type: boolean example: 'true' profileInstanceId: type: string description: The ID of the profile instance. example: '{PROFILE_INSTANCE}' source: type: string description: The source of what ran the segment job. example: scheduler status: type: string description: The status of the segment job. example: PROCESSING enum: - NEW - QUEUED - PROCESSING - CANCELLING - CANCELLED - FAILED - SUCCEEDED batchId: type: string description: The ID of the batch. example: 65e18145-a5e8-4993-94f3-c70fadaa1fef computeJobId: type: integer description: The compute job ID. format: int64 example: 1 computeGatewayJobId: type: string description: The compute gateway job ID, which can be use to get the job status from compute gateway API. example: c3505859-d256-45d0-a6f3-c25f8f8508f5 creationTime: type: integer description: The timestamp, as unix time in milliseconds, for when the segment job was created. format: int64 example: 1233456789000 updateTime: type: integer description: The timestamp, as unix time in milliseconds, for when the segment job was last updated. format: int64 example: 1233456789000 updateEpoch: type: integer segments: type: array items: $ref: '#/components/schemas/SegmentInfo' errors: type: array items: $ref: '#/components/schemas/SegmentJobErrorResponse' metrics: required: - profileSegmentationTime - totalTime type: object properties: totalTime: type: object properties: startTimeInMs: type: number description: The timestamp, as unix time in milliseconds, for when the segment job request is created. example: 123456789000.0 endTimeInMs: type: number description: The timestamp, as unix time in milliseconds, for when the segment job is completed. example: 123456799000.0 totalTimeInMs: type: number description: The time it takes for the segment job to complete in milliseconds. This is calculated by subtracting `startTimeInMs` from `endTimeInMs`. example: 10000.0 description: Information about the time it takes for the segment job to complete. profileSegmentationTime: type: object properties: startTimeInMs: type: number description: The timestamp, as unix time in milliseconds, for when the computation starts. example: 123456789000.0 endTimeInMs: type: number description: The timestamp, as unix time in milliseconds, for when the computation is completed. example: 123456799000.0 totalTimeInMs: type: number description: The computation time in milliseconds. This is calculated by subtracting the `startTimeInMs` from the `endTimeInMs`. example: 10000.0 description: Information about the computation time. totalProfiles: type: integer description: Total number of scanned profiles. format: int64 example: 1233456789000 totalProfilesByMergePolicy: type: object additionalProperties: type: number segmentedProfileCounter: type: object additionalProperties: type: number description: A map from segment definition IDs to the number of merged profiles in those segment definitions. segmentedProfileByNamespaceCounter: type: object additionalProperties: type: object additionalProperties: type: number description: The number of segmented profiles by namespace per segment definition ID. segmentedProfileByStatusCounter: type: object additionalProperties: type: object additionalProperties: type: number description: The number of segmented profiles by status per segment definition ID. description: Information about the segment job. requestId: type: string description: An optional ID that can be used for debugging purposes to identify the request. example: cc3d3381-8682-41d4-93bd-566e378624d3 properties: type: object schema: type: object additionalProperties: type: string modelName: type: string description: The name of the model. example: _xdm.context.profile _links: type: object additionalProperties: type: object additionalProperties: type: string description: A link to get the job status or cancel a submitted job. parameters: authorization: name: Authorization in: header description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en). required: true schema: type: string content-type: name: Content-Type in: header description: The type of content being sent in the body of the request. Should be 'application/json'. required: true schema: type: string x-api-key: name: x-api-key in: header description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en). required: true schema: type: string x-gw-ims-org-id: name: x-gw-ims-org-id in: header description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en). required: true schema: type: string x-sandbox-name: name: x-sandbox-name in: header description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information. required: true schema: type: string