cURL
curl -i -X POST "https://api.box.com/2.0/query_insights" \
-H "box-version: 2026.0" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"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"
}
}
}'client.query.create_query_insight_v2026_r0(
CreateQueryInsightV2026R0Query(
predicate=predicate,
params={"minAmount": 0},
ancestors=[QueryAncestorReferenceV2026R0(id="0", type="folder")],
group_by=[
QueryInsightsGroupByV2026R0(
field="".join([md_prefix, ".category"]), bucket_limit=5
)
],
),
metrics,
)await client.query.createQueryInsightV2026R0({
query: {
predicate: predicate,
params: { ['minAmount']: 0 },
ancestors: [
{ id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,
],
groupBy: [
{
field: ''.concat(mdPrefix, '.category') as string,
bucketLimit: 5,
} satisfies QueryInsightsGroupByV2026R0,
],
} satisfies QueryInsightsRequestBodyV2026R0QueryField,
metrics: metrics,
} satisfies QueryInsightsRequestBodyV2026R0);try await client.query.createQueryInsightV2026R0(requestBody: QueryInsightsRequestBodyV2026R0(query: QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate, params: ["minAmount": 0], ancestors: [QueryAncestorReferenceV2026R0(id: "0", type: "folder")], groupBy: [QueryInsightsGroupByV2026R0(field: "\(mdPrefix)\(".category")", bucketLimit: 5)]), metrics: metrics))client.getQuery().createQueryInsightV2026R0(new QueryInsightsRequestBodyV2026R0(new QueryInsightsRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf("minAmount", 0))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0("0", "folder"))).groupBy(Arrays.asList(new QueryInsightsGroupByV2026R0.Builder(String.join("", mdPrefix, ".category")).bucketLimit(5).build())).build(), metrics))await client.Query.CreateQueryInsightV2026R0Async(requestBody: new QueryInsightsRequestBodyV2026R0(query: new QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary<string, object>() { { "minAmount", 0 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: "0", type: "folder")}), GroupBy = Array.AsReadOnly(new [] {new QueryInsightsGroupByV2026R0(field: string.Concat(mdPrefix, ".category")) { BucketLimit = 5 }}) }, metrics: metrics));{
"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
}
}
}
}
]
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}Query
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.
POST
/
query_insights
cURL
curl -i -X POST "https://api.box.com/2.0/query_insights" \
-H "box-version: 2026.0" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-H "content-type: application/json" \
-d '{
"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"
}
}
}'client.query.create_query_insight_v2026_r0(
CreateQueryInsightV2026R0Query(
predicate=predicate,
params={"minAmount": 0},
ancestors=[QueryAncestorReferenceV2026R0(id="0", type="folder")],
group_by=[
QueryInsightsGroupByV2026R0(
field="".join([md_prefix, ".category"]), bucket_limit=5
)
],
),
metrics,
)await client.query.createQueryInsightV2026R0({
query: {
predicate: predicate,
params: { ['minAmount']: 0 },
ancestors: [
{ id: '0', type: 'folder' } satisfies QueryAncestorReferenceV2026R0,
],
groupBy: [
{
field: ''.concat(mdPrefix, '.category') as string,
bucketLimit: 5,
} satisfies QueryInsightsGroupByV2026R0,
],
} satisfies QueryInsightsRequestBodyV2026R0QueryField,
metrics: metrics,
} satisfies QueryInsightsRequestBodyV2026R0);try await client.query.createQueryInsightV2026R0(requestBody: QueryInsightsRequestBodyV2026R0(query: QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate, params: ["minAmount": 0], ancestors: [QueryAncestorReferenceV2026R0(id: "0", type: "folder")], groupBy: [QueryInsightsGroupByV2026R0(field: "\(mdPrefix)\(".category")", bucketLimit: 5)]), metrics: metrics))client.getQuery().createQueryInsightV2026R0(new QueryInsightsRequestBodyV2026R0(new QueryInsightsRequestBodyV2026R0QueryField.Builder(predicate).params(mapOf(entryOf("minAmount", 0))).ancestors(Arrays.asList(new QueryAncestorReferenceV2026R0("0", "folder"))).groupBy(Arrays.asList(new QueryInsightsGroupByV2026R0.Builder(String.join("", mdPrefix, ".category")).bucketLimit(5).build())).build(), metrics))await client.Query.CreateQueryInsightV2026R0Async(requestBody: new QueryInsightsRequestBodyV2026R0(query: new QueryInsightsRequestBodyV2026R0QueryField(predicate: predicate) { Parameters = new Dictionary<string, object>() { { "minAmount", 0 } }, Ancestors = Array.AsReadOnly(new [] {new QueryAncestorReferenceV2026R0(id: "0", type: "folder")}), GroupBy = Array.AsReadOnly(new [] {new QueryInsightsGroupByV2026R0(field: string.Concat(mdPrefix, ".category")) { BucketLimit = 5 }}) }, metrics: metrics));{
"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
}
}
}
}
]
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}{
"type": "error",
"status": 400,
"code": "item_name_invalid",
"message": "Method Not Allowed",
"context_info": {
"message": "Something went wrong"
},
"help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
"request_id": "abcdef123456"
}Learn more about Box SDK versioning strategy.
Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Headers
Version header.
Available options:
2026.0 Body
application/json
Request body describing the filtering, grouping, and metrics for an insights computation.
The filtering and grouping definition. Filters are applied first, followed by grouping, before metrics are computed.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Example:
{
"totalContractValue": {
"type": "sum",
"field": "enterprise_12345678:sales:contractValue"
},
"countContractType": {
"type": "count",
"field": "enterprise_12345678:sales:contractType"
}
}
Response
Returns the computed insight entries.
The computed results of an insights request, as a list of insight entries.
The list of computed insight entries. Each entry corresponds to a group, the overall dataset, or the aggregate of groups outside the top results.
Show child attributes
Show child attributes
Last modified on July 24, 2026
Was this page helpful?