--- schema_version: "1" id: 0f3f4dbbaecfa123d05a47230f25185e8a88de6500ce7ee54f83f95a8c15d3ee title: Data Extension Data collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/references/generated-api-specs/mc-custom_object_data.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-custom_object_data source_site: developer.salesforce.com content_type: documentation content_hash: 7b1d7a9a2cf0dd346c31c8e55e760bcdb9fd0521307c31a864b64a69a34eb9c9 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- Data Extension Data # Data Extension Data Use the data extension data endpoints to retrieve paginated data from a data extension in your Marketing Cloud Engagement account. Filtering, sorting, and paging are supported only with sendable data extensions. Requests to retrieve data from non-sendable data extensions can return a maximum of 200 rows. > **NOTE** > > There are several APIs related to data extensions: > > * Use this API to query data in a data extension. > * Use the [Data Extensions](/docs/marketing/marketing-cloud/references/mc-custom_objects) API to create, modify, and manage data extension objects. > * Use the [Data Extension Rows (Asynchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_async) and [Data Extension Rows (Synchronous)](/docs/marketing/marketing-cloud/references/mc-data_extension_rows_sync) APIs to add or update rows of data in a data extension. > * Use the [Data Extension Imports](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc-import_job_api) API to manage data import jobs. This table lists the use cases that this API supports. | Use Case | HTTP Verb | Endpoint | | --- | --- | --- | | [Get data extension data](/docs/marketing/marketing-cloud/references/mc-custom_object_data?meta=getData) | GET | /data/v1/customobjectdata/{id}/rowset | | [Get data extension data by key](/docs/marketing/marketing-cloud/references/mc-custom_object_data?meta=getDataByKey) | GET | /data/v1/customobjectdata/key/{key}/rowset | | [Get data by request token](/docs/marketing/marketing-cloud/references/mc-custom_object_data?meta=getDataByRequestToken) | GET | /data/v1/customobjectdata/token/{token}/rowset | > **NOTE** These APIs don't support retrieving data from a synchronized data extension. Append the operation endpoint addresses to this base URL, replacing `{subdomain}` with the unique subdomain for your Marketing Cloud Engagement tenant: **Version:** 1.0 ## Servers * `https://{subdomain}.rest.marketingcloudapis.com` * `subdomain (default N/A) The unique API subdomain for your Marketing Cloud Engagement tenant. You can find this value in the Installed Packages section of Marketing Cloud Engagement Setup.` ## Operations ### GET Retrieve data from a data extension by providing its ID. `GET /data/v1/customobjectdata/{id}/rowset` Operation ID: `getData`. #### Parameters * `Authorization` (header, string, required) A unique, time-limited token that you can use to issue requests to the Marketing Cloud Engagement API. Replace `YOUR_ACCESS_TOKEN` with your authentication token. _Example_ ``` Bearer YOUR_ACCESS_TOKEN ``` * `id` (path, string (uuid), required) The unique identifier of the data extension to retrieve data from. * `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls. Don’t specify this parameter if the `$offset` parameter is specified. Default: `1`. * `$pagesize` (query, integer) The number of records to return on each page of results. Default: `2500`. * `$fields` (query, string) A comma-separated list of the data extension fields to include in the response. If this parameter isn’t present in the request, the response includes all fields. * `$filter` (query, string) A string that describes the filter to apply to the response. You can only filter on primary keys. The filter must be URL encoded. Use single quotes for field values. Filters can include these operators: `eq`, `like`, `not`, and `and`. For example, to return only individuals in a data extension where the value of the LastName field is Cunningham, specify `$filter=LastName eq 'Cunningham'`. * `$orderBy` (query, string) The field and sort method to use to sort the results, such as `$orderBy=memberID ASC` to sort the results in ascending order by the value of the memberID field. If you don’t provide this value, the results are sorted in ascending order by the date and time when they were added to the data extension. * `$top` (query, integer) A fixed number of results to return in the response. For example, a value of `$top=3` returns the first three results that match the query parameters. * `$offset` (query, integer) The number of rows to skip before creating response items. When `$offset` is requested, the response contains the `$offset` property and the links contain `$offset` references. You can't specify this value if the `$page` parameter is also specified. #### Responses * **200** Indicates that the API accepted the request to retrieve data from the data extension. Media type: `application/json`. Schema: `getDataExtensionDataResponseBody`. _Example_ ``` { "links": { "previous": "/v1/customobjectdata/token/1392c2bf-c925-4207-ac52-4291c553e534/rowset?$page=1", "self": "/v1/customobjectdata/token/1392c2bf-c925-4207-ac52-4291c553e534/rowset?$page=2", "next": "/v1/customobjectdata/token/1392c2bf-c925-4207-ac52-4291c553e534/rowset?$page=3" }, "requestToken": "1392c2bf-c925-4207-ac52-4291c553e534", "tokenExpireDateUtc": "2023-09-22T17:34:36", "customObjectId": "7df6723b-76a1-e611-b68a-38eaa731a765", "customObjectKey": "data_extension0211233259337172", "pageSize": 2, "page": 2, "count": 54, "top": 0, "items": [ { "keys": { "CustID": "PU20" }, "values": { "Name": "Maria Jimenez", "AnniversaryDate": "3/20/2026 10:13:04 AM", "City": "Sacramento", "Country": "US", "Email": "mjimenez@example.com" } }, { "keys": { "CustID": "PU21" }, "values": { "Name": "Lincoln Ulrich", "AnniversaryDate": "3/20/2026 10:13:04 AM", "City": "Vancouver", "Country": "CA", "Email": "lulrich@example.com" } } ] } ``` * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct data extension ID, key, or token. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "custom object data cannot be retrieved for key: 685D0AF4-DBCF-4B42-A6BD-9E942DBA905A", "errorcode": 30003, "documentation": "" } ``` ### GET Retrieve data from a data extension by providing its external key. `GET /data/v1/customobjectdata/key/{key}/rowset` Operation ID: `getDataByKey`. #### Parameters * `key` (path, string, required) The external key of the data extension to retrieve data from. * `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls. Don’t specify this parameter if the `$offset` parameter is specified. Default: `1`. * `$pagesize` (query, integer) The number of records to return on each page of results. Default: `2500`. * `$fields` (query, string) A comma-separated list of the data extension fields to include in the response. If this parameter isn’t present in the request, the response includes all fields. * `$filter` (query, string) A string that describes the filter to apply to the response. You can only filter on primary keys. The filter must be URL encoded. Use single quotes for field values. Filters can include these operators: `eq`, `like`, `not`, and `and`. For example, to return only individuals in a data extension where the value of the LastName field is Cunningham, specify `$filter=LastName eq 'Cunningham'`. * `$orderBy` (query, string) The field and sort method to use to sort the results, such as `$orderBy=memberID ASC` to sort the results in ascending order by the value of the memberID field. If you don’t provide this value, the results are sorted in ascending order by the date and time when they were added to the data extension. When you use this parameter, the API automatically sets the value of the `$top` parameter to `100000`, even if you didn’t specify it in the request. * `$top` (query, integer) A fixed number of results to return in the response. For example, a value of `$top=3` returns the first three results that match the query parameters. * `$offset` (query, integer) The number of rows to skip before creating response items. When `$offset` is requested, the response contains the `$offset` property and the links contain `$offset` references. You can't specify this value if the `$page` parameter is also specified. #### Responses * **200** Indicates that the API accepted the request to retrieve data from the data extension. Media type: `application/json`. Schema: `getDataExtensionDataResponseBody`. _Example: same as GET /data/v1/customobjectdata/{id}/rowset 200 response._ * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct data extension ID, key, or token. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "custom object data cannot be retrieved for key: 685D0AF4-DBCF-4B42-A6BD-9E942DBA905A", "errorcode": 30003, "documentation": "" } ``` ### GET Retrieve data from a data extension by providing the request token. The \`$filter\`, \`$pagesize\`, \`$top\`, \`$fields\`, and \`$orderby\` parameters persist from the original query and can’t be specified. To limit the results that are returned, include the \`$page\` or \`$offset\` properties. `GET /data/v1/customobjectdata/token/{token}/rowset` Operation ID: `getDataByRequestToken`. #### Parameters * `token` (path, string, required) The request token from a previous data extension data GET request. * `$page` (query, integer) The page of results to retrieve. Each page includes the number of records specified by the `$pagesize` parameter. You can retrieve additional pages by incrementing this number in subsequent calls. Don’t specify this parameter if the `$offset` parameter is specified. Default: `1`. * `$offset` (query, integer) The number of rows to skip before creating response items. When `$offset` is requested, the response contains the `$offset` property and the links contain `$offset` references. You can't specify this value if the `$page` parameter is also specified. #### Responses * **200** Indicates that the API accepted the request to retrieve data from the data extension. Media type: `application/json`. Schema: `getDataExtensionDataResponseBody`. _Example: same as GET /data/v1/customobjectdata/{id}/rowset 200 response._ * **401** Indicates that the API wasn’t able to authorize your request. When you receive a 401 response, verify that you obtained an authorization token and that the token is still valid. Media type: `application/json`. Schema: `httpErrorResponseBody`. _Example_ ``` { "documentation": "https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm", "errorcode": 0, "message": "Not Authorized" } ``` * **403** This response indicates that the API accepted your request but couldn’t authorize it. When you receive a 403 response, make sure you have the necessary permission scope for the operation. You can modify permission scopes on the Installed Apps page in Marketing Cloud Engagement Setup. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "documentation": "", "errorcode": 20002, "message": "Insufficient privileges to complete this action." } ``` * **404** This response indicates that the URI in your request couldn’t be reached. When you receive a 404 response, verify that the request refers to the correct data extension ID, key, or token. Media type: `application/json`. Schema: `mceErrorResponseBody`. _Example_ ``` { "message": "custom object data cannot be retrieved for key: 685D0AF4-DBCF-4B42-A6BD-9E942DBA905A", "errorcode": 30003, "documentation": "" } ``` ## Schemas ### getDataExtensionDataResponseBody * `requestToken` (_string (guid)_) A unique token for the request. * `tokenExpireDateUtc` (_string (date-time)_) The date and time when the request token expires. * `customObjectId` (_string (guid)_) The unique, system-generated ID for the data extension that the data is retrieved from. * `customObjectKey` (_string_) The user-specified key for the data extension that the data is retrieved from. * `pageSize` (_number (integer)_) The number of results returned in a page of results. * `page` (_number (integer)_) The current page of results. * `count` (_number (integer)_) The total number of results returned for the request. * `top` (_number (integer)_) If the `$top` parameter was specified in the request, this property indicates the number of results returned in the request. If the `$top` parameter wasn’t specified, this value is 0. * `links` (_object_) * `self` (_string_) The request token for the current page of results. * `previous` (_string_) The request token for the previous page of results. * `next` (_string_) The request token for the next page of results. * `items` (_array of object_) * `keys` (_object_) An object that contains information about the primary key for the data extension. This object contains a key-value pair that corresponds to the primary key and the key value for the result item. * `values` (_object_) An object that contains the keys and values for the data columns retrieved from the data extension. ### httpErrorResponseBody * `documentation` (_string_) Contains a link to the [Marketing Cloud Engagement developer documentation page about handling REST API errors](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/error-handling.htm). * `errorcode` (_integer_) The error code. In some situations, this value can be 0. * `message` (_string_) The error message. ### mceErrorResponseBody * `documentation` (_string_) An empty string. * `errorcode` (_integer_) An internal error code. For a complete list of error codes, see [Handle Errors in REST API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/error-handling.html). * `message` (_string_) The error message.