Dataset expiration endpoint

Use the /ttl endpoint in the Data Hygiene API to schedule when datasets in Adobe Experience Platform should be deleted.

A dataset expiration is a delayed delete operation. The dataset is not protected in the interim and may be deleted by other means before its scheduled expiration.

Before deletion begins, you can cancel the expiration or change its scheduled time. To reopen a cancelled expiration, set a new expiry.

Once deletion begins, the expiration job is marked as executing and can no longer be modified. The dataset may be recoverable for up to seven days, but only through a manual Adobe service request. During deletion, the data lake, Identity Service, and Real-Time Customer Profile each remove the dataset contents separately. When deletion is complete, the expiration is marked as completed.

Advanced Data Lifecycle Management supports dataset deletions through the dataset expiration endpoint and ID deletions (row-level data) using primary identities via the workorder endpoint. You can also manage dataset expirations and record deletions through the Experience Platform UI. See the linked documentation for more information.

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.

List dataset expirations list

You can list all dataset expirations configured for your organization by making a GET request to the /ttl endpoint.

Filter results using query parameters to return only the expirations that meet your criteria. Each result includes status and configuration details for each dataset expiration.

API format

GET /ttl?{QUERY_PARAMETERS}

Request

The following request retrieves all dataset expirations updated before August 1, 2021, and last updated by a user whose name matches “Jane Doe”.

curl -X GET \
  https://platform.adobe.io/data/core/hygiene/ttl?updatedToDate=2021-08-01&author=LIKE%20%25Jane%20Doe%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-c9f113f2-d751-44bc-bc20-9d5ca0b6ae15",
      "datasetId": "3e9f815ae1194c65b2a4c5ea",
      "datasetName": "Acme_Profile_Engagements",
      "sandboxName": "acme-beta",
      "displayName": "Engagement Data Retention Policy",
      "description": "Scheduled expiry for Acme marketing data",
      "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
      "status": "pending",
      "expiry": "2027-01-12T17:15:31.000Z",
      "updatedAt": "2026-12-15T12:40:20.000Z",
      "updatedBy": "t.lannister@acme.com <t.lannister@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
    }
  ],
  "current_page": 0,
  "total_pages": 1,
  "total_count": 1
}

Look up a dataset expiration lookup

Retrieve the details for a specific dataset expiration configuration by making a GET request with either the dataset expiration ID or the dataset ID as the path parameter.

API format

GET /ttl/{ID}
GET /ttl/{ID}?include=history

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",
    "displayName": "Delete Acme Data before 2025",
    "description": "The Acme information in this dataset is licensed for our use through the end of 2024.",
    "imsOrg": "885737B25DC460C50A49411B@AdobeOrg",
    "status": "pending",
    "expiry": "2035-09-25T00:00:00Z",
    "updatedAt": "2025-05-01T19:00:55.000Z",
    "updatedBy": "Jane Doe <jdoe@adobe.com> 77A51F696282E48C0A494 012@64d18d6361fae88d49412d.e",
}

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 shows a truncated Catalog API response for a dataset with an expiration value of 32503680000000. The tag encodes the expiry as the number of milliseconds since 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 a dataset expiration create

Create a new dataset expiration configuration to define when a dataset will expire and be eligible for deletion.
Provide the dataset ID, expiry date or date-time (in ISO 8601 format), a display name, and (optionally) a description.

To create a dataset expiration, send a POST request as shown below.

API format

POST /ttl

Request

curl -X POST \
  https://platform.adobe.io/data/core/hygiene/ttl \
  -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}' \
  -H 'Content-Type: application/json' \
  -d '{
        "datasetId": "3e9f815ae1194c65b2a4c5ea",
        "expiry": "2030-12-31",
        "displayName": "Expiry rule for Acme customers",
        "description": "Set expiration for Acme customer dataset"
      }'

Response

A successful response returns an HTTP 201 (Created) status and the new dataset expiration configuration.

{
  "ttlId": "SD-2aaf113e-3f17-4321-bf29-a2c51152b042",
  "datasetId": "3e9f815ae1194c65b2a4c5ea",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Expiry rule for Acme customers",
  "description": "Set expiration for Acme customer dataset",
  "imsOrg": "{ORG_ID}",
  "status": "pending",
  "expiry": "2030-12-31T00:00:00Z",
  "updatedAt": "2025-01-02T10:35:45.000Z",
  "updatedBy": "s.stark@acme.com <s.stark@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
}

A 400 (Bad Request) HTTP status occurs if a dataset expiration already exists for the dataset. A 404 (Not Found) HTTP status occurs if no such dataset exists or you do not have access to the dataset.

Update a dataset expiration configuration update

To update an existing dataset expiration configuration, make a PUT request to /ttl/DATASET_EXPIRATION_ID. You can only update the displayName, description, and expiry fields of the configuration. Updates are only allowed when the expiration status is pending.

API format

PUT /ttl/{DATASET_EXPIRATION_ID}

Request

The following request updates the expiration, display name, and description for dataset expiration SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45:

curl -X PUT \
  https://platform.adobe.io/data/core/hygiene/ttl/SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45 \
  -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 '{
        "displayName": "Customer Dataset Expiry Rule",
        "description": "Updated description for Acme customer dataset",
        "expiry": "2031-06-15"
      }'

Response

A successful response returns HTTP status 200 (OK) and the updated dataset expiration configuration.

{
  "ttlId": "SD-c1f902aa-57cb-412e-bb2b-c70b8e1a5f45",
  "datasetId": "3e9f815ae1194c65b2a4c5ea",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Customer Dataset Expiry Rule",
  "description": "Updated description for Acme customer dataset",
  "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
  "status": "pending",
  "expiry": "2031-06-15T00:00:00Z",
  "updatedAt": "2031-05-01T14:11:12.000Z",
  "updatedBy": "b.tarth@acme.com <b.tarth@acme.com> 3E9F815AE1194C65B2A4C5EA@acme.com"
}

An unsuccessful response returns a 404 (Not Found) HTTP status if no such dataset expiration exists.

Cancel a dataset expiration delete

Cancel a pending dataset expiration configuration by making a DELETE request to /ttl/{ID}.

API format

DELETE /ttl/{ID}

Request

The following request cancels a dataset expiration with ID SD-d4a7d918-283b-41fd-bfe1-4e730a613d21:

curl -X DELETE \
  https://platform.adobe.io/data/core/hygiene/ttl/SD-d4a7d918-283b-41fd-bfe1-4e730a613d21 \
  -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 200 (OK) and the cancelled dataset expiration configuration. Not that the expiration’s status attribute is set to cancelled.

{
  "ttlId": "SD-d4a7d918-283b-41fd-bfe1-4e730a613d21",
  "datasetId": "5a9e2c68d3b24f03b55a91ce",
  "datasetName": "Acme_Customer_Data",
  "sandboxName": "acme-prod",
  "displayName": "Customer Dataset Expiry Rule",
  "description": "Cancelled expiry configuration for Acme customer dataset",
  "imsOrg": "C9D8E7F6A5B41234567890AB@AcmeOrg",
  "status": "cancelled",
  "expiry": "2032-02-28T00:00:00Z",
  "updatedAt": "2032-01-15T08:27:31.000Z",
  "updatedBy": "s.clegane@acme.com <s.clegane@acme.com> 5A9E2C68D3B24F03B55A91CE@acme.com"
}

Example 400 (Bad Request) response

A 400 error occurs when attempting to cancel a dataset that has an executing, completed, or cancelled expiration configuration.

{
  "type": "http://ns.adobe.com/aep/errors/HYGN-3102-400",
  "title": "The requested dataset already has an existing expiration. Additional detail: A TTL already exists for datasetId=686e9ca25ef7462aefe72c93",
  "status": 400,
  "report": {
    "tenantInfo": {
      "sandboxName": "prod",
      "sandboxId": "not-applicable",
      "imsOrgId": "{IMS_ORG_ID}"
    },
    "additionalContext": {
      "Invoking Client ID": "acp_privacy_hygiene"
    }
  },
  "error-chain": [
    {
      "serviceId": "HYGN",
      "errorCode": "HYGN-3102-400",
      "invokingServiceId": "acp_privacy_hygiene",
      "unixTimeStampMs": 1754408150394
    }
  ]
}

Appendix

Accepted query parameters query-params

The following table outlines the available query parameters when listing dataset expirations: