> ## Documentation Index > Fetch the complete documentation index at: https://developer.box.com/llms.txt > Use this file to discover all available pages before exploring further. # Create insights for Box items > Computes aggregated metrics over Box items matching a query predicate. Filters are applied first, followed by optional grouping, after which the requested metrics (such as `sum`, `avg`, `min`, `max`, and `count`) are computed for each resulting group or over the entire filtered dataset. Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/). ## OpenAPI ````yaml box-openapi-v2026.0.json POST /query_insights openapi: 3.0.2 info: title: Box Platform API description: >- [Box Platform](https://developer.box.com) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies. termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9 contact: name: Box, Inc url: https://developer.box.com email: devrel@box.com license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: '2026.0' x-box-commit-hash: 92c221bf9d servers: - url: https://api.box.com/2.0 description: Box Platform API server. security: - OAuth2Security: [] tags: - name: Automate Workflows description: Endpoints for listing and manually starting Automate workflow actions. x-box-tag: automate_workflows - name: Convert to Box note description: Create Box Notes from supported source content (for example Markdown). x-box-tag: notes - name: Query description: Query for your items. x-box-tag: query externalDocs: description: Box Developer Documentation. url: https://developer.box.com paths: /query_insights: post: tags: - Query summary: Create insights for Box items description: >- Computes aggregated metrics over Box items matching a query predicate. Filters are applied first, followed by optional grouping, after which the requested metrics (such as `sum`, `avg`, `min`, `max`, and `count`) are computed for each resulting group or over the entire filtered dataset. operationId: post_query_insights_v2026.0 parameters: - $ref: '#/components/parameters/BoxVersionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryInsightsRequestBody' responses: '200': description: Returns the computed insight entries. content: application/json: schema: $ref: '#/components/schemas/QueryInsights' '400': description: >- Returned when the query could not be parsed, the request body fails schema validation, or an unexpected JSON type was provided. content: application/json: schema: $ref: '#/components/schemas/ClientError' '401': description: >- Returned when the access token provided in the `Authorization` header is missing, not valid, or expired. content: application/json: schema: $ref: '#/components/schemas/ClientError' '403': description: Returned when the query is restricted for this enterprise or scope. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned when a referenced metadata template does not exist, or the user does not have access to it. content: application/json: schema: $ref: '#/components/schemas/ClientError' '429': description: Returned when the enterprise exceeds the allowed request rate. content: application/json: schema: $ref: '#/components/schemas/ClientError' '500': description: >- Returned when an unexpected server error occurs while computing insights. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: parameters: BoxVersionHeader: name: box-version in: header description: Version header. allowEmptyValue: false required: true schema: type: string enum: - '2026.0' example: '2026.0' schemas: QueryInsightsRequestBody: description: >- Request body describing the filtering, grouping, and metrics for an insights computation. type: object properties: query: description: >- The filtering and grouping definition. Filters are applied first, followed by grouping, before metrics are computed. type: object additionalProperties: false properties: predicate: description: >- A logical expression used to filter the dataset prior to metric computation, similar to an SQL `WHERE` clause. May include named parameters referenced as `:placeholder`. type: string example: >- EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2 params: description: >- A map of placeholder names (without the `:` prefix) to their values. Required only when the predicate contains parameter placeholders. The type of each value must match the type of the field it is compared to. type: object example: templateArg: enterprise_12345678:sales dateArg1: '2025-06-01T00:00:00-07:00' dateArg2: '2025-07-01T00:00:00-07:00' additionalProperties: {} ancestors: description: >- Restricts results to items contained within any of the specified ancestors. The user must have access to every listed ancestor. When omitted, insights are computed across all accessible items. type: array items: $ref: '#/components/schemas/QueryAncestorReference' group_by: description: >- Defines how data is grouped for insights computation. Currently only a single grouping field is supported. type: array items: $ref: '#/components/schemas/QueryInsightsGroupBy' required: - predicate metrics: description: >- A map of user-defined metric aliases to their definitions. A maximum of 10 metrics may be defined. Each alias must be a unique, non-empty string of up to 256 characters, containing only letters, digits, `_`, `-`, or `.`, and must not start with a digit, `_`, `-`, or `.`. May be empty to request only a total count. type: object example: totalContractValue: type: sum field: enterprise_12345678:sales:contractValue countContractType: type: count field: enterprise_12345678:sales:contractType additionalProperties: $ref: '#/components/schemas/QueryInsightsMetricDefinition' maxProperties: 10 example: 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 additionalProperties: false required: - query - metrics title: Query insights request body x-box-tag: query QueryInsights: description: >- The computed results of an insights request, as a list of insight entries. type: object properties: insights: description: >- The list of computed insight entries. Each entry corresponds to a group, the overall dataset, or the aggregate of groups outside the top results. type: array items: $ref: '#/components/schemas/QueryInsightEntry' example: 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 additionalProperties: false required: - insights title: Query insights x-box-resource-id: query_insights_v2026.0 x-box-tag: query ClientError: description: A generic error. type: object properties: type: description: The value will always be `error`. type: string example: error enum: - error nullable: false status: description: The HTTP status of the response. type: integer format: int32 example: 400 nullable: false code: description: A Box-specific error code. type: string example: item_name_invalid enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. type: string example: Method Not Allowed nullable: false context_info: description: >- A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example. type: object example: message: Something went wrong additionalProperties: {} nullable: true help_url: description: A URL that links to more information about why this error occurred. type: string example: >- https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ nullable: false request_id: description: >- A unique identifier for this response, which can be used when contacting Box support. type: string example: abcdef123456 nullable: false title: Client error x-box-resource-id: client_error_v2026.0 QueryAncestorReference: description: >- A reference to an ancestor entity used to restrict query results to that entity and its recursive descendants. type: object properties: id: description: The unique identifier of the ancestor entity. type: string example: '789' type: description: 'The type of the ancestor entity. Possible value: folder.' type: string example: folder additionalProperties: false required: - id - type title: Query ancestor reference x-box-tag: query QueryInsightsGroupBy: description: >- Defines a single grouping criterion for an insights request. Currently only a single grouping field is supported. type: object properties: field: description: >- The fully qualified field name to group by. Supports metadata and item properties. type: string example: enterprise_12345678:sales:contractType bucket_limit: description: >- The maximum number of buckets to return for the grouping. Defaults to `5`. type: integer format: int32 example: 3 default: 5 maximum: 10 minimum: 1 additionalProperties: false required: - field title: Query insights group by x-box-tag: query QueryInsightsMetricDefinition: description: >- Defines a single metric to compute, including the aggregation function and the field it is applied to. type: object properties: type: description: The aggregation function to apply. type: string example: sum enum: - sum - avg - min - max - count field: description: The fully qualified field name on which the metric is computed. type: string example: enterprise_12345678:sales:contractValue additionalProperties: false required: - type - field title: Query insights metric definition x-box-tag: query QueryInsightEntry: description: >- A single computed insight entry, containing its grouping keys (if applicable) and the computed metrics. type: object properties: key: description: >- The grouping key values associated with the entry. Contains one value per `group_by` field for `group` entries, and is empty for `overall` and `other` entries. type: array items: type: string example: ContractType1 example: - ContractType1 type: description: >- The type of insight entry, indicating how the associated metrics are aggregated. type: string example: group enum: - group - overall - other metrics: description: >- A map of metric aliases to their computed results. For `other` entries, the count is reported under the `totalCountBeyondTopGroups` key. type: object example: totalContractValue: type: sum values: sum: 180000 countContractType: type: count values: count: 245 additionalProperties: $ref: '#/components/schemas/QueryInsightMetricResult' additionalProperties: false required: - key - type - metrics title: Query insight entry x-box-resource-id: query_insight_entry_v2026.0 x-box-tag: query QueryInsightMetricResult: description: >- The computed result for a single metric, including the metric type and its computed value(s). type: object properties: type: description: The metric type that was computed. type: string example: sum values: description: >- The computed metric result(s), keyed by the metric function (for example `sum`, `avg`, `min`, `max`, or `count`). type: object example: sum: 50 additionalProperties: type: number additionalProperties: false required: - type - values title: Query insight metric result x-box-tag: query securitySchemes: OAuth2Security: type: oauth2 description: >- The access token received from the authorization server in the OAuth 2.0 flow. flows: authorizationCode: authorizationUrl: https://account.box.com/api/oauth2/authorize tokenUrl: https://api.box.com/oauth2/token scopes: root_readonly: Read all files and folders stored in Box root_readwrite: Read and write all files and folders stored in Box manage_app_users: Provision and manage app users manage_managed_users: Provision and manage managed users manage_groups: Manage an enterprise's groups manage_webhook: Create webhooks programmatically through the API manage_enterprise_properties: Manage enterprise properties manage_data_retention: Manage data retention polices manage_legal_hold: Manage Legal Holds ````