---
title: Get query suggestions
slug: '1459'
canonical_url: https://docs.coveo.com/en/1459/
collection: build-a-search-ui
source_format: adoc
---
# Get query suggestions
You can request [basic query expression (`q`)](https://docs.coveo.com/en/178/) completions from a [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [query suggestions](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/) by sending a GET or POST HTTP request to `+https://platform.cloud.coveo.com/rest/search/v2/querySuggest+`.

The Search API [query suggestion](https://docs.coveo.com/en/1015/) route supports several parameters which you can include either in the [query](https://docs.coveo.com/en/231/) string of a GET request, or in the JSON body of a POST request (see [QS parameters](https://docs.coveo.com/en/13#tag/Search-V2/operation/querySuggestGet/)).

> **Note**
>
> When using an OAuth2 token to [authenticate](https://docs.coveo.com/en/2120/) a GET or POST HTTP request to the Search API [query suggestion](https://docs.coveo.com/en/1015/) route, you must specify the unique identifier of the target [organization](https://docs.coveo.com/en/185/) by including the `organizationId` argument in the [query](https://docs.coveo.com/en/231/) string of your request.

## Query suggestion examples

. Requesting [query suggestions](https://docs.coveo.com/en/1015/) using the GET method:

```http
GET https://platform.cloud.coveo.com/rest/search/v2/querySuggest?locale=en&q=twa&searchHub=BookstoreSearch HTTP/1.1
​
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

. Requesting [query suggestions](https://docs.coveo.com/en/1015/) using the POST method:

```http
POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

```json
{
  "locale": "en",
  "q": "twa",
  "searchHub": "BookstoreSearch"
}
```

**200 OK response body (excerpt)**

```json
{
  "completions": [
    {
      "executableConfidence": 1,
      "expression": "mark twain",
      "highlighted": "[mark] {twa}[in]",
      "score": 14.525258530973204
    },
    {
      "executableConfidence": 0.6666666666666666,
      "expression": "[wes]{twa}[rd] [ho]",
      "highlighted": "",
      "score": 8.50548085208594
    },
    {
      "executableConfidence": 0.5,
      "expression": "hot water music",
      "highlighted": "[hot] (wat)[er] [music]",
      "score": 7.107770631785241
    },
    ...
  ]
}
```

> **Notes**
>
> * If the [query suggestion](https://docs.coveo.com/en/1015/) request is routed to a [query pipeline](https://docs.coveo.com/en/180/) with no associated [Coveo ML](https://docs.coveo.com/en/188/) [QS](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/), the request will return an empty `completions` array.
> 
> * In a `completions` array item:
> 
> ** The `score` property value only has relative significance within the same completions array.
>  
> For example, a suggestion with a score of `14.811407079917723` in the `completions` array of response **A* isn't necessarily less relevant than a suggestion with a score of ``24.32572887562528``2 in the `completions` array of response *B**.
> 
> ** The `highlighted` property uses the following logic:
> 
> *** Characters between curly braces, such as `+{cat}+`, indicate an exact match with [`q`](https://docs.coveo.com/en/13#operation/querySuggestGet-q).
> 
> *** Characters between square braces, such as `[cher]`, indicate completions.
> 
> *** Characters between parentheses, such as `(act)`, indicate corrections to [`q`](https://docs.coveo.com/en/178/).
> 
> ** The `executableConfidence` property contains a floating-point value between `0` and `1` which indicates how "`convinced`" [Coveo ML](https://docs.coveo.com/en/188/) is that performing a [query](https://docs.coveo.com/en/231/) with this suggestion as a [basic query expression](https://docs.coveo.com/en/178/) will return relevant results.
> The threshold from which [Coveo ML](https://docs.coveo.com/en/188/) considers a [query suggestion](https://docs.coveo.com/en/1015/) executable is `0.8`.

## Troubleshooting

If your [QS](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/) isn't behaving as expected, this may be due to a mismatch between the [`searchHub`](https://docs.coveo.com/en/13#operation/searchUsingPost-searchHub) value used in your Search API requests and the `[originLevel1](https://docs.coveo.com/en/1337/)` value used when logging [events](https://docs.coveo.com/en/260/) for the target [search interface](https://docs.coveo.com/en/2741/) through the Usage Analytics Write API.
It's important that these values match in any given [search interface](https://docs.coveo.com/en/2741/), since the [Coveo ML](https://docs.coveo.com/en/188/) service uses them as [filter](https://docs.coveo.com/en/2736/) [fields](https://docs.coveo.com/en/200/).

> **Note**
>
> The same relationship exists between the [`tab`](https://docs.coveo.com/en/13#operation/searchUsingPost-tab) value used in your Search API requests and the `[originLevel2](https://docs.coveo.com/en/1338/)` value used in your Usage Analytics Write API requests.

### Troubleshooting example

You have one [search interface](https://docs.coveo.com/en/2741/) for books and another for movies.

On the [Coveo Analytics](https://docs.coveo.com/en/182/) side, when logging [events](https://docs.coveo.com/en/260/) in these [search interfaces](https://docs.coveo.com/en/2741/), the [`originlevel1`](https://docs.coveo.com/en/1502#originlevel1-string) values specified in your requests are, respectively, `BookstoreSearch` and `MovieStoreSearch`.

On the Search API side, this translates into distinctive behavior from one `[searchHub](https://docs.coveo.com/en/1342/)` to another.

. You make the following request:

```http
POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

```json
{
  "q": "Dost",
  "searchHub": "BookstoreSearch"
}
```

The Search API returns the following completions, where the `Dostoevsky` suggestion is executable and highly recommended:

```json
{
  "completions": [
    {
      "executableConfidence": 1,
      "expression": "Dostoevsky",
      "highlighted": "{Dost}[oevsky]",
      "score": 56.135864235791246
    },
    ...
  ]
}
```

. You make the following request to the Search API:

```http
POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
```

**Payload**

```json
{
  "q": "Dost",
  "searchHub": "MovieStoreSearch"
}
```

The Search API returns the following completions, where `Dosti` (a successful Hindi film) is executable and highly recommended, and where `Dostoevsky` doesn't figure at all:

```json
{
  "completions": [
    ...
    {
      "executableConfidence": 1,
      "expression": "Dosti",
      "highlighted": "{Dost}[i]",
      "score": 35.183255413846215
    },
    ...
  ]
}
```

Hence, when in the `BookstoreSearch` [search interface](https://docs.coveo.com/en/2741/), it's important to pass `"searchHub": "BookstoreSearch"` for the relevant [query suggestion](https://docs.coveo.com/en/1015/) `Dostovesky` to be returned, instead of the Hindi film.

## Query suggestion parameters

See the reference documentation for [requesting query suggestions](https://docs.coveo.com/en/13#tag/Search-V2/operation/querySuggestGet/).