Dataset expiration endpoint
The /ttl
endpoint in the Data Hygiene API allows you to schedule expiration dates for datasets in Adobe Experience Platform.
A dataset expiration is only a timed-delayed delete operation. The dataset is not protected in the interim, so it may be be deleted by other means before its expiry is reached.
At any time before the dataset-delete is actually initiated, you can cancel the expiration or modify its trigger time. After cancelling a dataset expiration, you can reopen it by setting a new expiry.
Once the dataset deletion is initiated, its expiration job will be marked as executing
, and it may not be further altered. The dataset itself may be recoverable for up to seven days, but only through a manual process initiated through an Adobe service request. As the request executes, the data lake, Identity Service, and Real-Time Customer Profile begin separate processes to remove the dataset’s contents from their respective services. Once the data is deleted from all three services, the expiration is marked as executed
.
Getting started
The endpoint used in this guide is part of the Data Hygiene API. Before continuing, please review the API guide for information on required headers for CRUD operations, error messages, Postman collections, and how to read sample API calls.
x-sandbox-name: {SANDBOX_NAME}
header.List dataset expirations list
You can list all dataset expirations for your organization by making a GET request. Query parameters can be used to filter the response for appropriate results.
API format
GET /ttl?{QUERY_PARAMETERS}
{QUERY_PARAMETERS}
&
characters. Common parameters include limit
and page
for pagination purposes. For a full list of supported query parameters, refer to the appendix section.Request
curl -X GET \
https://platform.adobe.io/data/core/hygiene/ttl?updatedToDate=2021-08-01&author=LIKE%Jane Doe%25 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response lists the resulting dataset expirations. The following example has been truncated for space.
{
"results": [
{
"ttlId": "SD-b16c8b48-a15a-45c8-9215-587ea89369bf",
"datasetId": "629bd9125b31471b2da7645c",
"datasetName": "Sample Acme dataset",
"sandboxName": "hygiene-beta",
"imsOrg": "A2A5*EF06164773A8A49418C@AdobeOrg",
"status": "pending",
"expiry": "2050-01-01T00:00:00Z",
"updatedAt": "2023-06-09T16:52:44.136028Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e"
}
],
"current_page": 0,
"total_pages": 1,
"total_count": 1
}
totalRecords
ttlDetails
Look up a dataset expiration lookup
To lookup a dataset expiration, make a GET request with either the datasetId
or the ttlId
.
API format
GET /ttl/{DATASET_ID}?include=history
GET /ttl/{TTL_ID}
{DATASET_ID}
{TTL_ID}
Request
The following request looks up the expiration details for dataset 62759f2ede9e601b63a2ee14
:
curl -X GET \
https://platform.adobe.io/data/core/hygiene/ttl/62759f2ede9e601b63a2ee14 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns the details of the dataset expiration.
{
"ttlId": "SD-c8c75921-2416-4be7-9cfd-9ab01de66c5f",
"datasetId": "62759f2ede9e601b63a2ee14",
"datasetName": "XtVRwq9-38734",
"sandboxName": "prod",
"imsOrg": "A2A5*EF06164773A8A49418C@AdobeOrg",
"status": "pending",
"expiry": "2024-12-31T23:59:59Z",
"updatedAt": "2024-05-11T15:12:40.393115Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e",
"displayName": "Delete Acme Data before 2025",
"description": "The Acme information in this dataset is licensed for our use through the end of 2024."
}
ttlId
datasetId
datasetName
sandboxName
imsOrg
status
expiry
updatedAt
updatedBy
displayName
description
Catalog expiry tags
When using the Catalog API to look up dataset details, if the dataset has an active expiration it will be listed under tags.adobe/hygiene/ttl
.
The following JSON represents a truncated response for a dataset’s details from Catalog, which an expiration value of 32503680000000
. The tag’s value encodes the expiry as an integer number of milliseconds since the beginning of the Unix epoch.
{
"63212313c308d51b997858ba": {
"name": "Test Dataset",
"description": "A piecrust promise, made to be broken",
"imsOrg": "0FCC747E56F59C747F000101@AdobeOrg",
"sandboxId": "8dc51b90-d0f9-11e9-b164-ed6a398c8b35",
"tags": {
"adobe/hygiene/ttl": [ "32503680000000" ],
...
},
...
}
}
Create or update a dataset expiration create-or-update
Create or update an expiration date for a dataset through a PUT request. The PUT request uses either the datasetId
or the ttlId
.
API format
PUT /ttl/{DATASET_ID}
PUT /ttl/{TTL_ID}
{DATASET_ID}
{TTL_ID}
Request
The following request schedules a dataset 5b020a27e7040801dedbf46e
for deletion at the end of 2022 (Greenwich Mean Time). If no existing expiration is found for the dataset, a new expiration is created. If the dataset already has a pending expiration, that expiration is updated with the new expiry
value.
curl -X PUT \
https://platform.adobe.io/data/core/hygiene/ttl/5b020a27e7040801dedbf46e \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"expiry": "2024-12-31T23:59:59Z",
"displayName": "Delete Acme Data before 2025",
"description": "The Acme information in this dataset is licensed for our use through the end of 2024."
}'
expiry
displayName
description
Response
A successful response returns the details of the dataset expiration, with HTTP status 200 (OK) if a pre-existing expiration was updated, or 201 (Created) if there was no pre-existing expiration.
{
"ttlId": "SD-c8c75921-2416-4be7-9cfd-9ab01de66c5f",
"datasetId": "5b020a27e7040801dedbf46e",
"imsOrg": "A2A5*EF06164773A8A49418C@AdobeOrg",
"status": "pending",
"expiry": "2024-12-31T23:59:59Z",
"updatedAt": "2022-05-09T22:38:40.393115Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e",
"displayName": "Delete Acme Data before 2025",
"description": "The Acme information in this dataset is licensed for our use through the end of 2024."
}
ttlId
datasetId
imsOrg
status
expiry
updatedAt
updatedBy
Cancel a dataset expiration delete
You can cancel a dataset expiration by making a DELETE request.
pending
can be canceled. Attempting to cancel an expiration that has executed or is already canceled returns an HTTP 404 error.API format
DELETE /ttl/{EXPIRATION_ID}
{EXPIRATION_ID}
ttlId
of the dataset expiration that you want to cancel.Request
The following request cancels a dataset expiration with ID SD-b16c8b48-a15a-45c8-9215-587ea89369bf
:
curl -X DELETE \
https://platform.adobe.io/data/core/hygiene/ttl/SD-b16c8b48-a15a-45c8-9215-587ea89369bf \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 204 (No Content), and the expiration’s status
attribute is set to cancelled
.
Retrieve the expiration status history of a dataset retrieve-expiration-history
You can look up the expiration status history of a specific dataset by using the query parameter include=history
in a lookup request. The result includes information about about the creation of the dataset expiration, any updates that have been applied, and its cancellation or execution (if applicable). You can also use the ttlId
of the dataset expiration.
API format
GET /ttl/{DATASET_ID}?include=history
GET /ttl/{TTL_ID}
{DATASET_ID}
{TTL_ID}
Request
curl -X GET \
https://platform.adobe.io/data/core/hygiene/ttl/62759f2ede9e601b63a2ee14?include=history \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns the details of the dataset expiration, with a history
array providing the details its status
, expiry
, updatedAt
, and updatedBy
attributes for each of its recorded updates.
{
"ttlId": "SD-b16c8b48-a15a-45c8-9215-587ea89369bf",
"datasetId": "62759f2ede9e601b63a2ee14",
"datasetName": "Example Dataset",
"sandboxName": "prod",
"displayName": "Expiration Request 123",
"description": "Expiration Request 123 Description",
"imsOrg": "0FCC747E56F59C747F000101@AdobeOrg",
"status": "cancelled",
"expiry": "2022-05-09T23:47:30.071186Z",
"updatedAt": "2022-05-09T23:47:30.071186Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e",
"history": [
{
"status": "created",
"expiry": "2032-12-31T23:59:59Z",
"updatedAt": "2022-05-09T22:38:40.393115Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e"
},
{
"status": "updated",
"expiry": "2032-12-31T23:59:59Z",
"updatedAt": "2022-05-09T22:41:46.731002Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e"
},
{
"status": "cancelled",
"expiry": "2022-05-09T23:47:30.071186Z",
"updatedAt": "2022-05-09T23:47:30.071186Z",
"updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e"
}
]
}
ttlId
datasetId
datasetName
sandboxName
displayName
description
imsOrg
history
status
, expiry
, updatedAt
, and updatedBy
attributes for the expiration at the time of the update.Appendix
Accepted query parameters query-params
The following table outlines the available query parameters when listing dataset expirations:
description
, displayName
, and datasetName
parameters all contain the ability to searched for by LIKE values. This means that you can find scheduled dataset expirations named: “Name123”, “Name183”, “DisplayName1234” by searching for the string “Name1”.author
created_by
is a match for the search string. If the search string begins with LIKE
or NOT LIKE
, the remainder is treated as an SQL search pattern. Otherwise, the entire search string is treated as a literal string that must exactly match the entire content of a created_by
field.author=LIKE %john%
, author=John Q. Public
cancelledDate
/ cancelledToDate
/ cancelledFromDate
updatedDate=2022-01-01
completedDate
/ completedToDate
/ completedFromDate
completedToDate=2021-11-11-06:00
createdDate
Note that dates without a time (like
2021-12-07
) represent the datetime at the beginning of that day. Thus, createdDate=2021-12-07
refers to any expiration created on 7 December 2021, from 00:00:00
through 23:59:59.999999999
(UTC).createdDate=2021-12-07
createdFromDate
createdFromDate=2021-12-07T00:00:00Z
createdToDate
createdToDate=2021-12-07T23:59:59.999999999Z
datasetId
datasetId=62b3925ff20f8e1b990a7434
datasetName
datasetName=Acme
description
description=Handle expiration of Acme information through the end of 2024.
displayName
displayName=License Expiry
executedDate
/ executedFromDate
/ executedToDate
executedDate=2023-02-05T19:34:40.383615Z
expiryDate
/ expiryToDate
/ expiryFromDate
expiryFromDate=2099-01-01&expiryToDate=2100-01-01
limit
limit=50
orderBy
orderBy
query parameter specifies the sorting order of the results returned by the API. Use it to arrange the data based on one or more fields, either in ascending (ASC) or descending (DESC) order. Use the + or - prefix to signify ASC, DESC respectively. The following values are accepted: displayName
, description
, datasetName
, id
, updatedBy
, updatedAt
, expiry
, status
.-datasetName
orgId
x-gw-ims-org-id
headers, and is ignored unless the request supplies a service token.orgId=885737B25DC460C50A49411B@AdobeOrg
page
page=3
sandboxName
x-sandbox-name
header. Use sandboxName=*
to include dataset expirations from all sandboxes.sandboxName=dev1
search
Matches expirations where the specified string is an exact match for the expiration ID, or is contained in any of these fields:
- author
- display name
- description
- display name
- dataset name
search=TESTING
status
status=pending,cancelled
ttlId
ttlID=SD-c8c75921-2416-4be7-9cfd-9ab01de66c5f
updatedDate
/ updatedToDate
/ updatedFromDate
createdDate
/ createdFromDate
/ createdToDate
, but matches against a dataset expiration’s update time instead of creation time.An expiration is considered updated on every edit, including when it is created, cancelled, or executed.
updatedDate=2022-01-01