Get fields

Retrieve a list of currently available data source fields and custom fields.

List data source fields

GET https://api.supermetrics.com/enterprise/v2/query/fields
  • api_key string
    Conditional. API key when not using an authorization header. See authentication for more.
  • ds_id string
    Required. Data source ID. See data sources for more.
  • ds_accounts string | string[]
    Optional. List of data source account IDs we should return custom fields for.
  • ds_users string | string[]
    Conditional. List of data source usernames we should limit to, when searching for target data source accounts. Required when ds_accounts is defined.
Request
GET https://api.supermetrics.com/enterprise/v2/query/fields?json={
    "api_key": "<api key>",
    "ds_id": "GA",
    "ds_accounts": "567890",
    "ds_users": "info@supermetrics.com"
}
Response
PropertyTypeDescription
meta > request_idstring API request ID
datads_field[] Data source field objects derived from ds_field
HTTP 200 OK
{
    "meta": {
        "request_id": "xNqw8ZX6MRHdhR1D_oxPsWJwHuVnFSlU"
    },
    "data": [
        {
            "@type": "ds_dimension",
            "field_id": "dataSourceName",
            "field_name": "Data source",
            "field_type": "dim",
            "data_type": "string.text.value",
            "description": "The name of the source...",
            "group_name": "DATASOURCE",
            "is_filterable": true
        },
        {
            "@type": "ds_dimension",
            "field_id": "today",
            "field_name": "Today",
            "field_type": "dim",
            "data_type": "string.time.date",
            "description": "Today's date, e.g. 2017-01-31",
            "group_name": "TIME",
            "is_filterable": false
        },
        {
            "@type": "ds_dimension",
            "field_id": "year",
            "field_name": "Year",
            "field_type": "dim",
            "data_type": "string.time.year",
            "description": "",
            "group_name": "TIME",
            "is_filterable": false
        },
        {
            "@type": "ds_metric",
            "field_id": "c_goal4abandonrate_123456789",
            "field_name": "New user flow (goal 4) abandon rate",
            "field_type": "met",
            "data_type": "float.number.ratio",
            "description": "goal4abandonrate metric for Account 567890",
            "group_name": "CUSTOM GOAL METRICS",
            "is_filterable": true,
            "is_non_aggregatable": false
        }
    ]
}

Custom fields

  • This endpoint can also return custom fields, identifiable by c_ prefix in the field ID.

  • Custom fields are created inside the data source service, like Facebook Ads, and are usually account specific. They might change at any point.

  • Endpoint to list data source fields does not retrieve fields from the source API in real time.

  • If two accounts have the same fields with the same field ID, only the first field is returned. The field name will be a combination of both fields, if they are different.

Field changes

  • Please note that field ID values can change. Usually, this is due to mandatory data source API changes, such as migrating to a new major version.

  • This endpoint does not return fields that have sunset, meaning the data source API no longer supports them.

  • All planned field changes are documented and communicated beforehand. Using previous field IDs in queries will be supported, when possible.

Non-aggregatable metrics

Metric fields marked as non-aggregatable can't be summed or averaged. This is because the field value depends on data that is either more granular, or not available from the source API.

Non-aggregatable fields are commonly unique, total, or already averaged metrics. These include fields such as reach and total budget.

Missing something?

If you find that we are missing information you absolutely need, please let us know.

Object reference

ds_field
PropertyTypeDescription
field_idstring Field ID. Note that this value can change. See field changes.
field_namestring Field name
field_typestring
Field type
dimDimension
metMetric
data_typestring Field data type. See field data types for more.
descriptionstring Field description, if any. Defaults to an empty string.
group_namestring Field group name in product UIs, always in uppercase
is_filterablestring Whether field can be used in query filter string

ds_metric
PropertyTypeDescription
is_non_aggregatablebool Whether metric value is non-aggregatable
Last updated 2023-02-28 UTC.