---
title: "Aggregate values"
slug: "aggregate-values"
description: "Learn how the aggregate values adapter sums chosen fields across nested array entries to return a single total per parent item."
updated: 2026-06-04T07:44:46Z
published: 2026-06-04T07:44:46Z
canonical: "docs.supermetrics.com/aggregate-values"
---

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

# Aggregate values

For each parent item under `dataPath`, the `aggregate_values` adapter looks up the array at `valuesPath` and sums each field named in `fields` across all entries. The single aggregated object replaces the original array in place, and any fields not listed in `fields` are dropped from the result.

Use this when an API returns per-variation or per-segment breakdowns nested under a category, and you want a single row with totals rather than one row per breakdown.

| Field | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `dataPath` | string | `$.*` | Yes | JSONPath to the iterable of parent items. |
| `valuesPath` | string | `$.*` | Yes | JSONPath, relative to each parent item, pointing at the array of objects to aggregate. |
| `fields` | array | – | Yes | Field names to sum. Must be a non-empty array. Only these fields appear in the aggregated result. |

## Aggregation behavior

| Value type | Behavior |
| --- | --- |
| Integer or float | Summed directly. |
| Numeric string (for example, `"150"`) | Auto-cast to a number and summed. |
| `null` | Treated as `0` — the field still appears in the result. |
| Field missing from some entries | Missing entries contribute `0`; the field still appears if present in at least one entry. |
| Field absent from all entries | Not added to the result at all. |
| Non-numeric string | Raises an error. |
| Array, object, or boolean | Raises an error. |

> **Note:** If `valuesPath` resolves to an empty array or does not exist on a given item, that item is left unchanged — no error is raised.

Below you can find a before/after example. The original response has one entry per variation:

```
{
  "data": [
    {
      "time": "2025-09-01",
      "messages": {
        "email": [
          {
            "variation_name": "A",
            "sent": 150,
            "opens": 45,
            "clicks": 12
          },
          {
            "variation_name": "B",
            "sent": 170,
            "opens": 62,
            "clicks": 18
          }
        ]
      }
    }
  ]
}
```

After the adapter runs, the variations are collapsed into a single object with summed totals (`variation_name` is dropped because it is not in `fields`):

```
{
  "data": [
    {
      "time": "2025-09-01",
      "messages": {
        "email": {
          "sent": 320,
          "opens": 107,
          "clicks": 30
        }
      }
    }
  ]
}
```

Configuration:

```
"response": {
  "dataRows": {
    "source": "jsonPath",
    "value": "$.data.*"
  },
  "dataAdapters": {
    "items": [
      {
        "type": "aggregate_values",
        "config": {
          "dataPath": "$.data.*",
          "valuesPath": "$.messages.email.*",
          "fields": [
            "sent",
            "opens",
            "clicks"
          ]
        }
      }
    ]
  }
}
```

Below you can find example field definitions that read from the transformed structure:

```
[
  {
    "id": "time",
    "label": "Time",
    "dataType": "string.time.date_time",
    "value": {
      "source": "jsonPath",
      "value": "$.time"
    }
  },
  {
    "id": "sent",
    "label": "Sent",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.messages.email.sent"
    }
  },
  {
    "id": "opens",
    "label": "Opens",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.messages.email.opens"
    }
  },
  {
    "id": "clicks",
    "label": "Clicks",
    "dataType": "int.number.value",
    "value": {
      "source": "jsonPath",
      "value": "$.messages.email.clicks"
    }
  }
]
```