> ## 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.

# Query resources

Query for your items.

## Query insight entry

A single computed insight entry, containing its grouping keys (if applicable) and the computed metrics.

<Accordion title="Attributes and example">
  | Property  | Type              | Required | Description                                                                                                                                                     |
  | --------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `key`     | array of `string` | Yes      | 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`    | `enum<string>`    | Yes      | The type of insight entry, indicating how the associated metrics are aggregated. Available options: `group`, `overall`, `other`.                                |
  | `metrics` | `object`          | Yes      | A map of metric aliases to their computed results. For `other` entries, the count is reported under the `totalCountBeyondTopGroups` key.                        |

  ```json Example theme={null}
  {
    "key": [
      "ContractType1"
    ],
    "type": "group",
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "values": {
          "sum": 180000
        }
      },
      "countContractType": {
        "type": "count",
        "values": {
          "count": 245
        }
      }
    }
  }
  ```
</Accordion>

## Query insights

The computed results of an insights request, as a list of insight entries.

<Accordion title="Attributes and example">
  | Property   | Type                                                 | Required | Description                                                                                                                                       |
  | ---------- | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `insights` | array of [Query insight entry](#query-insight-entry) | Yes      | The list of computed insight entries. Each entry corresponds to a group, the overall dataset, or the aggregate of groups outside the top results. |

  ```json Example theme={null}
  {
    "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
            }
          }
        }
      }
    ]
  }
  ```
</Accordion>

## Query result entry

A single item matching the query. Always includes the item `type` and `id`. If a `fields` parameter was specified in the request, then additional item and/or metadata fields will be provided.

<Accordion title="Attributes and example">
  | Property | Type     | Required | Description                                 |
  | -------- | -------- | -------- | ------------------------------------------- |
  | `id`     | `string` | Yes      | The unique identifier of the matching item. |
  | `type`   | `string` | Yes      | The type of the matching item.              |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "file"
  }
  ```
</Accordion>

## Query results

A paginated list of items matching the query, using milestone-based marker pagination.

<Accordion title="Attributes and example">
  | Property      | Type                                               | Required | Description                                                                                                                                        |
  | ------------- | -------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `entries`     | array of [Query result entry](#query-result-entry) | Yes      | The list of items matching the query predicate.                                                                                                    |
  | `next_marker` | `string`                                           | Yes      | The marker for the start of the next page of results. When `null`, there are no further results available. Can be `null`.                          |
  | `limit`       | `integer`                                          | Yes      | The limit that was used for this request. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "file",
        "box": {
          "item": {
            "name": "My Form"
          }
        },
        "enterprise_12345678": {
          "book": {
            "$parent": "file_12345",
            "$scope": "enterprise_12345678",
            "$template": "book",
            "$version": 4,
            "isbn": "1871263670",
            "purchasePrice": 234.57,
            "publicationYear": "1937"
          }
        }
      }
    ],
    "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=",
    "limit": 1
  }
  ```
</Accordion>