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

Documentation Index

Aggregate values

Aggregation behavior