---
title: "POST /v1/query/search"
method: POST
path: "/v1/query/search"
tags: ["query"]
---

# POST /v1/query/search

`POST /v1/query/search`

The Cloud Search Query API provides the search method, which returns the most relevant results from a user query. The results can come from Google Workspace apps, such as Gmail or Google Drive, or they can come from data that you have indexed from a third party. **Note:** This API requires a standard end user account to execute. A service account can't perform Query API requests directly; to use a service account to perform queries, set up [Google Workspace domain-wide delegation of authority](https://developers.google.com/workspace/cloud-search/docs/guides/delegation/).

## Request body

- SearchRequest — The search API request. NEXT ID: 26
  - `requestOptions` RequestOptions — Shared request options for all RPC methods.
    - `languageCode` string — The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. For translations. Set this field using the language set in browser or for the page. In the event that the user's language preference is known, set this field to the known user language. When specified, the documents in search results are biased towards the specified language. The Suggest API uses this field as a hint to make better third-party autocomplete predictions.
    - `debugOptions` DebugOptions — Shared request debug options for all cloudsearch RPC methods.
      - `enableDebugging` boolean — If you are asked by Google to help with debugging, set this field. Otherwise, ignore this field.
    - `timeZone` string — Current user's time zone id, such as "America/Los_Angeles" or "Australia/Sydney". These IDs are defined by [Unicode Common Locale Data Repository (CLDR)](http://cldr.unicode.org/) project, and currently available in the file [timezone.xml](http://unicode.org/repos/cldr/trunk/common/bcp47/timezone.xml). This field is used to correctly interpret date and time queries. If this field is not specified, the default time zone (UTC) is used.
    - `clientDisplayLanguageCode` string — The BCP-47 language code, such as "pt" or "en". It represents the user's preferred Display Language.
    - `searchApplicationId` string — The ID generated when you create a search application using the [admin console](https://support.google.com/a/answer/9043922).
  - `query` string — The raw query string. See supported search operators in the [Narrow your search with operators](https://support.google.com/cloudsearch/answer/6172299)
  - `sortOptions` SortOptions
    - `operatorName` string — The name of the operator corresponding to the field to sort on. The corresponding property must be marked as sortable.
    - `sortOrder` 'ASCENDING' | 'DESCENDING' — Ascending is the default sort order
  - `contextAttributes` ContextAttribute[] — Context attributes for the request which will be used to adjust ranking of search results. The maximum number of elements is 10.
    - `name` string — The name of the attribute. It should not be empty. The maximum length is 32 characters. The name must start with a letter and can only contain letters (A-Z, a-z) or numbers (0-9). The name will be normalized (lower-cased) before being matched.
    - `values` string[] — Text values of the attribute. The maximum number of elements is 10. The maximum length of an element in the array is 32 characters. The value will be normalized (lower-cased) before being matched.
  - `start` integer — Starting index of the results.
  - `queryInterpretationOptions` QueryInterpretationOptions — Options to interpret user query.
    - `enableVerbatimMode` boolean — Enable this flag to turn off all internal optimizations like natural language (NL) interpretation of queries, supplemental result retrieval, and usage of synonyms including custom ones. Nl interpretation will be disabled if either one of the two flags is true.
    - `disableSupplementalResults` boolean — Use this flag to disable supplemental results for a query. Supplemental results setting chosen at SearchApplication level will take precedence if set to True.
    - `disableNlInterpretation` boolean — Flag to disable natural language (NL) interpretation of queries. Default is false, Set to true to disable natural language interpretation. NL interpretation only applies to predefined datasources.
  - `facetOptions` FacetOptions[]
    - `integerFacetingOptions` IntegerFacetingOptions — Used to specify integer faceting options.
      - `integerBuckets` string[] — Buckets for given integer values should be in strictly ascending order. For example, if values supplied are (1,5,10,100), the following facet buckets will be formed {<1, [1,5), [5-10), [10-100), >=100}.
    - `objectType` string — If object_type is set, only those objects of that type will be used to compute facets. If empty, then all objects will be used to compute facets.
    - `sourceName` string — Source name to facet on. Format: datasources/{source_id} If empty, all data sources will be used.
    - `operatorName` string — The name of the operator chosen for faceting. @see cloudsearch.SchemaPropertyOptions
    - `numFacetBuckets` integer — Maximum number of facet buckets that should be returned for this facet. Defaults to 10. Maximum value is 100.
  - `dataSourceRestrictions` DataSourceRestriction[] — The sources to use for querying. If not specified, all data sources from the current search application are used.
    - `source` Source — Defines sources for the suggest/search APIs.
      - `predefinedSource` 'NONE' | 'QUERY_HISTORY' | 'PERSON' | 'GOOGLE_DRIVE' | 'GOOGLE_GMAIL' | 'GOOGLE_SITES' | 'GOOGLE_GROUPS' | 'GOOGLE_CALENDAR' | 'GOOGLE_KEEP' — Predefined content source for Google Apps.
      - `name` string — Source name for content indexed by the Indexing API.
    - `filterOptions` FilterOptions[] — Filter options restricting the results. If multiple filters are present, they are grouped by object type before joining. Filters with the same object type are joined conjunctively, then the resulting expressions are joined disjunctively. The maximum number of elements is 20. NOTE: Suggest API supports only few filters at the moment: "objecttype", "type" and "mimetype". For now, schema specific filters cannot be used to filter suggestions.
      - `objectType` string — If object_type is set, only objects of that type are returned. This should correspond to the name of the object that was registered within the definition of schema. The maximum length is 256 characters.
      - `filter` Filter — A generic way of expressing filters in a query, which supports two approaches: **1. Setting a ValueFilter.** The name must match an operator_name defined in the schema for your data source. **2. Setting a CompositeFilter.** The filters are evaluated using the logical operator. The top-level operators can only be either an AND or a NOT. AND can appear only at the top-most level. OR can appear only under a top-level AND.
        - `valueFilter` ValueFilter
          - `operatorName` string — The `operator_name` applied to the query, such as *price_greater_than*. The filter can work against both types of filters defined in the schema for your data source: 1. `operator_name`, where the query filters results by the property that matches the value. 2. `greater_than_operator_name` or `less_than_operator_name` in your schema. The query filters the results for the property values that are greater than or less than the supplied value in the query.
          - `value` Value — Definition of a single value with generic type.
            - `integerValue` string, int64
            - `doubleValue` number, double
            - `booleanValue` boolean
            - `timestampValue` string, google-datetime
            - `dateValue` Date — Represents a whole calendar date, for example a date of birth. The time of day and time zone are either specified elsewhere or are not significant. The date is relative to the [Proleptic Gregorian Calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar). The date must be a valid calendar date between the year 1 and 9999.
              - …
            - `stringValue` string
        - `compositeFilter` CompositeFilter
          - `logicOperator` 'AND' | 'OR' | 'NOT' — The logic operator of the sub filter.
          - `subFilters` Filter[] — Sub filters.
  - `pageSize` integer — Maximum number of search results to return in one page. Valid values are between 1 and 100, inclusive. Default value is 10. Minimum value is 50 when results beyond 2000 are requested.

## Response `200`

Successful response

---

[API](https://skmtc.net/google/apis/cloudsearch.md) · [All operations](https://skmtc.net/google/apis/cloudsearch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/cloudsearch/versions/d64d6afc59a6/schema)