Use the dataSets object to get information about your audience.

The name and ID of your audience. The ID is required for mutations.
The names and IDs of consent groups in your audience. The IDs are necessary for updating contacts' consent statuses.
The contact attributes available in your audience. You may need them for adding and updating contacts.
The reference sets directly connected to your audience. To get the list of all reference sets in your Connect subscription, see Query reference sets.

Getting the audience profile

Here is how to check basic information about your audience (name, ID and consent groups).

query {
    dataSets(filter: [{ field: "type", eq: "AUDIENCE" }]) {
    nodes {
      dataSetId
      name
      consentGroups {
        id
        name
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "dataSetId": "123456789-0000000000000000000",
          "name": "Demo audience",
          "consentGroups": [
            {
              "id": "1111111111-0000-00000-00000000000",
              "name": "Newsletters"
            },
            {
              "id": "1111111111-0000-00000-00000000000",
              "name": "Promotions"
            },
            {
              "id": "1111111111-0000-00000-00000000000",
              "name": "Information"
            },
            {
              "id": "1111111111-0000-00000-00000000000",
              "name": "Custom"
            }
          ]
        }
      ]
    }
  }
}

Arguments

Arguments supported by the dataSets object

Argument	Nested field	Values	Definition
`filter`	`field`	String. Valid value: `type`.	You can use this filter for other fields as well, but in the current query it is important to specify the type of the dataset you need. ⚠️If you omit this filter, you will get both the audience and reference sets in the response.
	`eq`	String. Valid value: `AUDIENCE`.	The value that the `type` field must be equal to.

Fields

The query returns the fields nested into the nodes field

Field	Nested field	Values	Required?	Definition
`dataSetId`		ID	Required	The ID of an audience (assigned automatically)
`name`		String	Optional	The name of the audience
`type`		String. Valid value:`AUDIENCE`.	Optional	The type of the dataset you are querying
`consentGroups`	`id`	ID	Optional	The ID of a consent group
	`name`	String	Optional	The name of a consent group

Possible error messages

Error code	Definition
`CONSENT_GROUPS_FOR_DATASET_NOT_DEFINED`	There are no consent groups in the audience at the moment.

Getting contact attributes

Contact attributes are the fields that modify contacts in your audience (name, email address, location, age group and so on). You can get them using the attributes field.

query {
  dataSets(filter: [{ field: "type", eq: "AUDIENCE" }]) {
    nodes {
      attributes {
        name
        type
        category
        identifyAs {
          key
          channels
        }
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "attributes": [
            {
              "name": "Unique ID",
              "type": "TEXT",
              "category": "Contact information",
              "identifyAs": {
                "key": true,
                "channels": null
              }
            },
            {
              "name": "Email Address",
              "type": "TEXT",
              "category": "Contact information",
              "identifyAs": {
                "key": null,
                "channels": [
                  "EMAIL"
                ]
              }
            },
            {
              "name": "SMS Phone Number",
              "type": "TEXT",
              "category": "Contact information",
              "identifyAs": {
                "key": null,
                "channels": [
                  "SMS"
                ]
              }
            },
            {
              "name": "First Name",
              "type": "TEXT",
              "category": "Contact information",
              "identifyAs": null
            },
            {
              "name": "iPhone user",
              "type": "BOOLEAN",
              "category": "Demographic",
              "identifyAs": null
            },
            {
              "name": "Opt-In Date",
              "type": "DATE",
              "category": "Demographic",
              "identifyAs": null
            }
          ]
        }
      ]
    }
  }
}

Arguments

Arguments supported by the dataSets object

Argument	Nested field	Values	Definition
`filter`	`field`	String. Valid value: `type`.	You can use this filter for other fields as well, but in the current query it is important to specify the type of the dataset you need. ⚠️If you omit this filter, you will get both the audience and reference sets in the response.
	`eq`	String. Valid value: `AUDIENCE`.	The value that the `type` field must be equal to.

Fields

The query returns the fields nested into the nodes field

Field	Values	Definition
`attributes`	Object	An object containing contact attributes

Fields nested into the attributes field

Field	Nested field	Values	Definition
`name`		String	The name of an attribute
`type`		One of the following values: - `TEXT` - `NUMBER` - `BOOLEAN` - `DATE`	The data format of an attribute
`decimalPrecision`		Integer from 0 to 14. For non-numeric fields, the value is `null`.	The number of decimal places displayed. Applies to numeric values only
`category`		String	The category that an attribute belongs to. Query the `dataSetAttributeCategories` object to get all available attribute categories.
`identifyAs`	`key`	Boolean - `true`. The attribute acts as a key value in the dataset. - `false`. The attribute is marked as addressable. - `null`. The attribute is neither a key value, nor an addressable.	Lets you check if an attribute acts as a key value in the dataset or is marked as addressable.
	`channels`	Either of the following values: - `EMAIL` - `SMS`Applies to attributes marked as addressable.	Communication channel. Applies to addressable attributes (the `key` value for them is `false`).

Getting connected reference sets

To get the reference sets connected to your audience, use the associations field in the dataSets query. Note that this query returns only those reference sets that are connected to the audience directly, not through another reference set.

query  {
  dataSets(filter: [{ field: "type", eq: "AUDIENCE" }]) {
    nodes {
      associations {
        to {
          dataSetId
          name
        }
        mappings {
          fromAttribute
          toAttribute
        }
      }
    }
  }
}

{
  "data": {
    "dataSets": {
      "nodes": [
        {
          "associations": [
            {
              "to": {
                "dataSetId": "e83a688c-e53e-4a1c-8565-0000000001",
                "name": "Physical store clients"
              },
              "mappings": [
                {
                  "fromAttribute": "Unique ID",
                  "toAttribute": "ID"
                }
              ]
            },
            {
              "to": {
                "dataSetId": "b4fc145e-680a-4fc6-9d7a-0000000000002",
                "name": "Focus group participants"
              },
              "mappings": [
                {
                  "fromAttribute": "Unique ID",
                  "toAttribute": "ID"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Arguments

Arguments supported by the dataSets object

Argument	Nested field	Values	Definition
`filter`	`field`	String. Valid value: `type`.	You can use this filter for other fields as well, but in the current query it is important to specify the type of the dataset you need. ⚠️If you omit this filter, you will get both the audience and reference sets in the response.
	`eq`	String. Valid value: `AUDIENCE`.	The value that the `type` field must be equal to.

Fields

The query returns the fields nested into the nodes field

Field	Values	Required?	Description
`associations`	Object	Optional	See nested fields

Fields nested into to associations field

Field	Nested field	Required?	Definition
`to`	`dataSetId`	Optional	The ID of the reference set connected to your audience
	`name`	Optional	The name of the reference set connected to your audience
`mappings`	`fromAttribute`	Optional	The attribute in the audience that has been linked to a reference set
	`toAttribute`	Optional	The attribute in a reference set that has been linked to the audience