Query insights

Query insights API lets you compute aggregated insights (sums, averages, counts, and more) over items that match a metadata-based query. The system applies the specified filters first, then performs aggregation based on the provided grouping criteria, if any.

To get insights, call the POST https://api.box.com/2.0/query/insights endpoint.

Parameters

To make a call, you must pass the following parameters. The request body has two top-level fields: query and metrics. Mandatory parameters are in bold.

Parameter	Type	Description	Example
query	object	Defines the filtering conditions and grouping parameters for an insights request. Holds predicate, params, ancestors, and group_by together (not mutually exclusive).	ancestors
query.predicate	string	Filters the dataset before the metric computation. The predicate syntax is similar to an SQL WHERE clause and can include parameterized arguments.	enterprise_12345678:book:amount >= :value
query.params	object	Must include a key for each placeholder, where the key matches the placeholder name without the : prefix. Value types must match the field types used in the predicate. Required only if the predicate contains parameter placeholders (for example, :param).	{ "value": 100 }
query.ancestors	array of objects	Filters results based on item ancestry. Each object needs an id and type (such as folder). Returns items contained within any of the specified ancestors. The user must have access to all provided ancestors, otherwise the request is rejected. If empty or omitted, insights are computed across all accessible items (root context, 0).	[{ "id": "123", "type": "folder" }]
query.group_by	array of objects	Specifies how data is grouped. Each entry defines a grouping field and an optional bucket limit. Only a single group-by field is currently supported. Grouping is applied after filters and before metric computation. Grouping on high-cardinality fields can error; keep cardinality below 10,000.
[{ "field": "enterprise_12345678:book:category", "bucket_limit": 5 }]
query.group_by[].field	string	Fully qualified field name to group by. Supported fields include metadata and item properties (see supported field types).	enterprise_12345678:book:category
query.group_by[].bucket_limit	integer	Maximum number of buckets to return for the grouping. Defaults to 5, maximum allowed value is 10.	5
metrics	object (map)	A set of named metrics to compute. Each entry maps a user-defined alias to a metric operation applied to a field. Metrics are evaluated after filters (and grouping, if specified). Maximum 10 metrics in a request.	See examples below.
metrics.<alias>.type	string	Aggregation function to apply. Supported values: sum, avg, min, max, count.	count
metrics.<alias>.field	string	Fully qualified field name on which the metric is computed.	enterprise_12345678:product:category

Metric names

Each key in the metrics object is an alias defined by you for the metric.

Naming convention

• Must be a non-empty string
• Must be unique within the request
• Maximum length: 256 characters
• Allowed characters: letters (a–z, A–Z), digits (0–9), and special characters _, -, and .
• Must not start with a digit or special character
• Whitespace and other special characters are not allowed

Behavior

• If group_by is not specified, metrics are computed over the entire filtered dataset (ungrouped aggregation).
• If metrics is an empty object (), a default totalResultCount count metric is returned over the filtered dataset (see Total document count example).

Examples

Total contract value

Get total contract value and counts for top 3 contract types created in June 2025.

Request:

{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ],
      "group_by": [
        {
          "field": "enterprise_12345678:sales:contractType",
          "bucket_limit": 3
        }
      ]
    },
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "countContractType": {
        "type": "count",
        "field": "enterprise_12345678:sales:contractType"
      }
    }
  }

Response:

{
  "insights": [
    {
      "key": [ "ContractType1" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 180000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 245
          }
        }
      }
    },
    {
      "key": [ "ContractType4" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 100000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 185
          }
        }
      }
    },
    {
      "key": [ "ContractType2" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 200000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 150
          }
        }
      }
    },
    {
      "key": [],
      "type": "other",
      "metrics": {
        "totalCountBeyondTopGroups": {
          "type": "count",
          "values": {
            "count": 165
          }
        }
      }
    }
  ]
}

Overall average, minimum, maximum contract value

Get overall average, minimum, and maximum contract value for contracts created in June 2025.

Request:

{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {
      "avgContractValue": {
        "type": "avg",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "minContractValue": {
        "type": "min",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "maxContractValue": {
        "type": "max",
        "field": "enterprise_12345678:sales:contractValue"
      }
    }
  }

Response:

{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "avgContractValue": {
            "type": "avg",
            "values": {
              "avg": 45055.50
            }
          },
          "minContractValue": {
            "type": "min",
            "values": {
              "min": 22000
            }
          },
          "maxContractValue": {
            "type": "max",
            "values": {
              "max": 75000
            }
          }
        }
      }
    ]
  }

Total document count

Get total document count only by passing an empty metrics object.

Request:

{
    "query": {
      "predicate": "EXISTS(:templateArg)",
      "params": {
        "templateArg": "enterprise_12345678:sales"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {}
  }

Response:

{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "totalResultCount": {
            "type": "count",
            "values": {
              "count": 12345
            }
          }
        }
      }
    ]
  }

Response fields

Field	Type	Description	Example
insights	array	The calculated results of the request. Each entry corrensponds to a specific result type and contains the associated grouping keys (if applicable) and calculated metrics.	See below.
insights.key	array of objects	The grouping key values for the entry. Structure depends on the entry type.	See below.
insights.key	array of strings	One value for each group_by field.	["Shoe"]
insights.type	string	The type of insight entry. One of group, overall, or other.	group
insights.metrics	object	A map of the calculated metric results. Each key is a user-defined metric alias. Each value contains the metric type and its calculated values. The count metric for the other type is in the totalCountBeyondTopGroups key.	"metrics": {"totalPrice": {"type": "sum","values": {"sum": 50}}

Insight entry types

Type	Description
group	Metrics for a specific group defined by group_by. key contains one value per group_by field, for example [“Shoe”] for category = "Shoe".
overall	Metrics calculated across the entire dataset (no grouping). key is always an empty array [].
other	Aggregated count for results outside the top returned groups. An empty array [] represents all remaining groups not included in the top results.

Bucket ordering

For requests with group_by, bucket ordering is implicit and always descending by item count (the number of documents in each bucket). The largest buckets are returned first. This ordering cannot be customized.

For the Enum and Taxonomy fields, deleted options can temporarily appear in top groups while the deletion job is in progress. Such groups have their keys shown as [DELETED].

Error codes

The list below is not exhaustive, additional error codes and details can be introduced as the API evolves.

Error Code	Error Type	Error Message
400	BAD_REQUEST	Expected JSON with type string or Failed to parse query: Unexpected end of input message. Returned when the query cannot be parsed or an unexpected JSON is provided.
401	UNAUTHORIZED	The access token provided is invalid. Returned when an invalid or expired access token is used.
403	FORBIDDEN	Query is restricted for this enterprise/scope.
404	INSTANCE_NOT_FOUND	The templates you referenced were not found.
429	RATE_LIMIT_EXCEEDED	EnterpriseId is being rate limited.
500	INTERNAL_SERVER_ERROR	Internal server error.