Data Extension Data

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": ""
  }