> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pretectum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Data Objects

> Retrieve a paginated list of data objects within a specific dataset

The List Data Objects endpoint returns all data objects within a specific dataset. Data objects are the actual records in your master data repository, containing field values that conform to the schema structure.

## Prerequisites

* A Pretectum API key (see [API Keys](/api-reference/authentication/api-keys))
* Permission to access data objects in your tenant
* Valid business area ID (see [List Business Areas](/api-reference/business-areas/list))
* Valid schema ID (see [List Schemas](/api-reference/schemas/list))
* Valid dataset ID (see [List Datasets](/api-reference/datasets/list))

## Authentication

Include your API key in the `Authorization` header.

```bash theme={null}
Authorization: pre_your_api_key
```

## Request

### Path Parameters

<ParamField path="businessAreaId" type="string" required>
  The unique identifier of the business area. You can obtain this from the [List Business Areas](/api-reference/business-areas/list) endpoint.
</ParamField>

<ParamField path="schemaId" type="string" required>
  The unique identifier of the schema. You can obtain this from the [List Schemas](/api-reference/schemas/list) endpoint.
</ParamField>

<ParamField path="datasetId" type="string" required>
  The unique identifier of the dataset containing the data objects. You can obtain this from the [List Datasets](/api-reference/datasets/list) endpoint.
</ParamField>

### Query Parameters

<ParamField query="pageKey" type="string">
  A pagination token for retrieving the next page of results. This value is returned in the response as `nextPageKey` when more results are available.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required initialValue="pre_your_api_key">
  Your Pretectum API key. Create one in the Pretectum app under **Configuration → API Keys**.
</ParamField>

<ParamField header="Accept" type="string" default="application/json">
  The response content type. Currently only `application/json` is supported.
</ParamField>

### Example Requests

<CodeGroup>
  ```bash cURL theme={null}
  # List all data objects in a dataset
  curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects" \
    -H "Authorization: pre_your_api_key" \
    -H "Accept: application/json"

  # Paginate through data objects
  curl -X GET "https://api.pretectum.io/v1/businessareas/20240115103000123a1b2c3d4e5f6789012345678901234/schemas/20240115103000456d1e2f3a4b5c6789012345678901234/datasets/20240925152201042a1b2c3d4e5f6789012345678901234/dataobjects?pageKey=eyJMYXN0RXZhbHVhdGVkS2V5Ijp7Li4ufQ" \
    -H "Authorization: pre_your_api_key" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const apiKey = 'pre_your_api_key';
  const businessAreaId = '20240115103000123a1b2c3d4e5f6789012345678901234';
  const schemaId = '20240115103000456d1e2f3a4b5c6789012345678901234';
  const datasetId = '20240925152201042a1b2c3d4e5f6789012345678901234';

  async function getDataObjects(businessAreaId, schemaId, datasetId, pageKey = null) {
    const url = new URL(
      `https://api.pretectum.io/v1/businessareas/${businessAreaId}/schemas/${schemaId}/datasets/${datasetId}/dataobjects`
    );
    if (pageKey) {
      url.searchParams.set('pageKey', pageKey);
    }

    const response = await fetch(url, {
      headers: {
        'Authorization': apiKey,
        'Accept': 'application/json'
      }
    });

    return response.json();
  }

  const dataObjects = await getDataObjects(businessAreaId, schemaId, datasetId);
  console.log(`Retrieved ${dataObjects.items.length} data objects`);
  dataObjects.items.forEach(obj => {
    console.log(`- ${obj._dataObjectId}: ${obj['First Name']} ${obj['Last Name']}`);
  });
  ```

  ```python Python theme={null}
  import requests

  api_key = 'pre_your_api_key'
  business_area_id = '20240115103000123a1b2c3d4e5f6789012345678901234'
  schema_id = '20240115103000456d1e2f3a4b5c6789012345678901234'
  dataset_id = '20240925152201042a1b2c3d4e5f6789012345678901234'

  def get_data_objects(business_area_id, schema_id, dataset_id, page_key=None):
      params = {}
      if page_key:
          params['pageKey'] = page_key

      response = requests.get(
          f'https://api.pretectum.io/v1/businessareas/{business_area_id}/schemas/{schema_id}/datasets/{dataset_id}/dataobjects',
          params=params,
          headers={
              'Authorization': api_key,
              'Accept': 'application/json'
          }
      )
      response.raise_for_status()
      return response.json()

  data_objects = get_data_objects(business_area_id, schema_id, dataset_id)
  print(f"Retrieved {len(data_objects['items'])} data objects")
  for obj in data_objects['items']:
      print(f"- {obj['_dataObjectId']}: {obj.get('First Name', '')} {obj.get('Last Name', '')}")
  ```
</CodeGroup>

## Response

A successful request returns an object containing an array of data objects and pagination information.

<ResponseField name="items" type="array" required>
  An array of data objects. Each object contains dynamic fields based on the schema definition, plus system-generated metadata fields.

  <Expandable title="Data object properties">
    <ResponseField name="_dataObjectId" type="string">
      The unique identifier for the data object.
    </ResponseField>

    <ResponseField name="_version" type="integer">
      The version number of the data object. This increments each time the object is updated. Use this value when updating the object to prevent concurrent modification conflicts.
    </ResponseField>

    <ResponseField name="_errors" type="array">
      An array of validation errors for the data object. Each error object contains:

      * `name`: The field name that has the error
      * `errors`: Description of the validation error
    </ResponseField>

    <ResponseField name="[Field Name]" type="varies">
      Dynamic fields based on the schema definition. Field names match the schema field names (not field IDs). The data type depends on the field configuration in the schema.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPageKey" type="string">
  A pagination token for retrieving the next page of results. If this field is present, more data objects are available. Pass this value as the `pageKey` query parameter in your next request.
</ResponseField>

### Example Response

```json theme={null}
{
  "items": [
    {
      "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
      "_version": 1,
      "_errors": [],
      "First Name": "John",
      "Last Name": "Smith",
      "Email": "john.smith@example.com",
      "Phone": "+1 555-123-4567",
      "Date of Birth": "01/15/1985",
      "Status": "Active"
    },
    {
      "_dataObjectId": "20240601120100456g2b3c4d5e6f7890123456789012345",
      "_version": 2,
      "_errors": [],
      "First Name": "Jane",
      "Last Name": "Doe",
      "Email": "jane.doe@example.com",
      "Phone": "+1 555-987-6543",
      "Date of Birth": "03/22/1990",
      "Status": "Active"
    }
  ],
  "nextPageKey": "eyJMYXN0RXZhbHVhdGVkS2V5Ijp7ImRhdGFPYmplY3RJZCI6IjIwMjQwNjAxMTIwMTAw..."
}
```

### Response with Validation Errors

Data objects may have validation errors if the data doesn't conform to schema rules:

```json theme={null}
{
  "items": [
    {
      "_dataObjectId": "20240601120000123f1a2b3c4d5e6789012345678901234",
      "_version": 1,
      "_errors": [
        {
          "name": "Email",
          "errors": "Invalid email format"
        },
        {
          "name": "Phone",
          "errors": "Phone number is required"
        }
      ],
      "First Name": "John",
      "Last Name": "Smith",
      "Email": "invalid-email",
      "Phone": null,
      "Status": "Active"
    }
  ]
}
```

### Empty Response

If the dataset has no data objects, the response will contain an empty items array:

```json theme={null}
{
  "items": []
}
```

## Error Responses

| Status Code | Description |
| - | - |
| `401 Unauthorized` | The API key is missing, malformed, unknown, inactive, expired or deleted. Check the key in **Configuration → API Keys**. |
| `403 Forbidden` | Your application client does not have permission to access data objects. Contact your tenant administrator. |
| `404 Not Found` | The specified business area, schema, or dataset does not exist, or you do not have access to it. |
| `500 Internal Server Error` | An unexpected error occurred on the server. Try again later or contact support. |

## Pagination

When a dataset contains many data objects, results are paginated. Use the `nextPageKey` from the response to fetch subsequent pages:

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function getAllDataObjects(businessAreaId, schemaId, datasetId) {
    const allDataObjects = [];
    let pageKey = null;

    do {
      const response = await getDataObjects(businessAreaId, schemaId, datasetId, pageKey);
      allDataObjects.push(...response.items);
      pageKey = response.nextPageKey;
      console.log(`Retrieved ${allDataObjects.length} data objects so far...`);
    } while (pageKey);

    return allDataObjects;
  }

  const allDataObjects = await getAllDataObjects(businessAreaId, schemaId, datasetId);
  console.log(`Total data objects: ${allDataObjects.length}`);
  ```

  ```python Python theme={null}
  def get_all_data_objects(business_area_id, schema_id, dataset_id):
      all_data_objects = []
      page_key = None

      while True:
          response = get_data_objects(business_area_id, schema_id, dataset_id, page_key)
          all_data_objects.extend(response['items'])
          print(f"Retrieved {len(all_data_objects)} data objects so far...")

          page_key = response.get('nextPageKey')
          if not page_key:
              break

      return all_data_objects

  all_data_objects = get_all_data_objects(business_area_id, schema_id, dataset_id)
  print(f"Total data objects: {len(all_data_objects)}")
  ```
</CodeGroup>

## Best Practices

1. **Use pagination**: Always handle pagination for large datasets. Don't assume all data will fit in a single response.
2. **Cache schema information**: Fetch the schema once to understand field names and types, then reuse it when processing data objects.
3. **Handle validation errors**: Check the `_errors` array to identify data quality issues that need attention.
4. **Use version for updates**: Store the `_version` value if you plan to update the data object later.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Data Object" icon="plus" href="/api-reference/dataobjects/create">
    Add new records to a dataset
  </Card>

  <Card title="Update Data Object" icon="pen" href="/api-reference/dataobjects/update">
    Modify existing records
  </Card>

  <Card title="Delete Data Object" icon="trash" href="/api-reference/dataobjects/delete">
    Remove records from a dataset
  </Card>

  <Card title="Get Data Object by Primary Key" icon="fingerprint" href="/api-reference/dataobjects/get-by-primary-key">
    Fetch one record by its primary key value
  </Card>

  <Card title="Search Data Objects" icon="magnifying-glass" href="/api-reference/dataobjects/search">
    Search across all datasets
  </Card>
</CardGroup>