> ## 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 for Box items > Runs a query to discover Box items using a logical predicate that can filter across item fields and metadata templates. Results can be sorted, paginated, and shaped to include additional item or metadata fields. Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/). ## OpenAPI ````yaml box-openapi-v2026.0.json POST /query 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: post: tags: - Query summary: Query for Box items description: >- Runs a query to discover Box items using a logical predicate that can filter across item fields and metadata templates. Results can be sorted, paginated, and shaped to include additional item or metadata fields. operationId: post_query_v2026.0 parameters: - $ref: '#/components/parameters/BoxVersionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequestBody' responses: '200': description: Returns a paginated list of items matching the query. content: application/json: schema: $ref: '#/components/schemas/QueryResults' '400': description: >- Returned when the query could not be parsed, the request body fails schema validation, a referenced scope is not valid, 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 matched too many items, or too many inaccessible items, to be processed. content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: >- Returned when a referenced metadata template or item 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 processing the query. 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: QueryRequestBody: description: >- Request body describing the query to run, including the filtering predicate, optional sorting, pagination, and the fields to return for each result. type: object properties: query: description: >- The query definition, including the filtering predicate and its optional parameters and ancestor restrictions. type: object additionalProperties: false properties: predicate: description: >- A logical expression used to filter the dataset, similar to an SQL `WHERE` clause. May include named parameters referenced as `:placeholder`. type: string example: >- enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name 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: price: 100 name: The Hobbit additionalProperties: {} ancestors: description: >- Restricts results to the specified ancestor entities and their recursive descendants. The user must have read access to every listed ancestor. type: array items: $ref: '#/components/schemas/QueryAncestorReference' required: - predicate order_by: description: >- The sorting criteria for the result set. Entries are applied sequentially to define multi-level sorting. type: array items: $ref: '#/components/schemas/QueryOrderBy' limit: description: >- The maximum number of results to return. Defaults to `50` when not provided. type: integer format: int32 example: 1 default: 50 maximum: 100 minimum: 0 fields: description: >- Controls which additional fields are included in each result entry. Each value must be one of: a fully qualified item field key (for example `box:item:name`), a metadata template key to hydrate the full template (for example `enterprise_12345678:project`), or a specific metadata template field key to hydrate a single field from the template (for example `enterprise_12345678:project:name`). When omitted, entries include only the item type and identifier. type: array items: type: string example: box:item:name example: - box:item:name - enterprise_12345678:book marker: description: >- An opaque token returned from a previous response, used to continue retrieval. When provided, all other request parameters must exactly match those of the original request. type: string example: xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA= example: query: predicate: >- enterprise_12345678:book:purchasePrice >= :price AND box:item:name = :name params: price: 100 name: The Hobbit ancestors: - id: '789' type: folder order_by: - field_key: enterprise_12345678:book:purchasePrice direction: asc limit: 1 fields: - box:item:name - enterprise_12345678:book additionalProperties: false required: - query title: Query request body x-box-tag: query QueryResults: description: >- A paginated list of items matching the query, using milestone-based marker pagination. type: object properties: entries: description: The list of items matching the query predicate. type: array items: $ref: '#/components/schemas/QueryResultEntry' next_marker: description: >- The marker for the start of the next page of results. When `null`, there are no further results available. type: string example: xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA= nullable: true limit: description: >- 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. type: integer format: int32 example: 50 example: 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 additionalProperties: false required: - entries - next_marker - limit title: Query results x-box-resource-id: query_results_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 QueryOrderBy: description: >- A single sorting criterion applied to the query result set. Multiple criteria are applied sequentially in the order specified. type: object properties: field_key: description: The fully qualified field key to sort by. type: string example: enterprise_12345678:book:purchasePrice direction: description: The direction in which results are ordered. type: string example: asc enum: - asc - desc additionalProperties: false required: - field_key - direction title: Query order by x-box-tag: query QueryResultEntry: description: >- 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. type: object properties: id: description: The unique identifier of the matching item. type: string example: '12345' type: description: The type of the matching item. type: string example: file additionalProperties: {} required: - id - type title: Query result entry x-box-resource-id: query_result_entry_v2026.0 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 ````