Docs Overview/
How to Use API to Implement Grouping Aggregation in a Single Call/

How to Use API to Implement Grouping Aggregation in a Single Call

The EdgeOne data query APIs supports passing the DimensionName parameter to specify the grouping dimension in the returned data, achieving the effect of obtaining multiple groups of data in a single query. This can significantly reduce API call frequency and simplify the operation of fetching statistical data. For example, if the input parameter DimensionName = domain is passed in a call, the returned data will be grouped separately for each domain name.

Applicable Scope

The group query feature is suitable for the following APIs:
DescribeTimingL7OriginPullData

Use Cases

The following scenarios show how to combine the DimensionName and Filters parameters to achieve efficient and flexible data access. For queries involving a large number of domain names or fine-grained status codes, priority recommendation is to use Filters for pre-filtering and choose appropriate query granularity (Interval).

Scenario 1: Batch Obtain Domain Name Data

Query metric data for multiple domain names in a single request to avoid initiating separate calls for each domain name.
Input parameter example
{
  "ZoneIds": ["*"],
  "MetricNames": ["l7Flow_inFlux_hy"],
  "StartTime": "2025-12-01T00:00:00Z",
  "EndTime": "2025-12-02T00:00:00Z",
  "Interval": "hour",
  "Filters": [
    {
      "Key": "domain",
      "Operator": "equals",
      "Value": ["example.com", "api.example.com"]
    }
  ],
  "DimensionName": "domain"
}

Scenario 2: Aggregate and Analyze by Status Code Type

Retrieve aggregate data grouped by major category of origin status codes (such as 2xx, 4xx, 5xx).
Input parameter example
{
  "ZoneIds": ["*"],
  "MetricNames": ["l7Flow_request_hy"],
  "StartTime": "2025-12-01T00:00:00Z",
  "EndTime": "2025-12-01T12:00:00Z",
  "Interval": "hour",
  "Filters": [
    {
      "Key": "originStatusCode",
      "Operator": "equals", 
      "Value": ["2xx", "4xx", "5xx"]
    }
  ],
  "DimensionName": "origin-status-code-category"
}

Use Limits

A single request can return a maximum number of 50,000 TimingDataItem data items. The calculation rules for the total count are as follows:
count × time point count × dimension value count = total number of data items
Metric count: the list length of MetricNames.
Time point count: (EndTime - StartTime) / Interval.
Dimension value count:
When DimensionName is not specified, aggregate data at the account level by default, and the dimension value count is 1.
When DimensionName = domain, the count of dimension values equals the list length of domains specified by the domain filter condition in Filters.
When DimensionName = origin-status-code-category, the dimension value count defaults to 6.
When DimensionName = origin-status-code, the dimension value count defaults to 600.
DimensionName can be used in combination with Filters to limit the count of dimension values by specifying the filter criteria corresponding to DimensionName in Filters.

Example

Take querying time series data for a specific status code dimension in an hour as an example. Suppose the query condition is as follows:
MetricNames = ["l7Flow_request_hy"] (metric count = 1)
StartTime = 2025-10-01T06:00:00+08:00, EndTime = 2025-10-01T06:59:59+08:00, Interval = "min" (time point count = 60)
DimensionName = origin-status-code, Filters = [{"originStatusCode": ["0", "4xx", "5xx"]}] (dimension value count = 201)
The total count of data items is:
1 × 60 × 201 = 12060
The limit is not exceeded.
Note:
If the total count of queried data items exceeds 50,000, the system will return an error LimitExceeded.TimingDataItemLimitExceeded.
At this point, adjust the input parameters to reduce queried data items per query to not exceeding 50,000. You may employ the following methods:
1. Reduce the count of time points
Shorten the query time range (time between StartTime and EndTime).
Select a larger time interval (Interval).
2. Reduce the count of dimension values
Adjust Filters and specify a shorter domain or originStatusCode list.
3. Reduce the count of metric values
Adjust MetricNames and specify fewer queried metrics.