---
type: api
title: Get a query rule
description: Get details about a query rule within a query ruleset.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-query-rules-get-rule
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-query-rules-get-rule
products:
  - Elasticsearch
---

# Get a query rule

Availability: 8.15+

## Paths

- `GET` `/_query_rules/{ruleset_id}/_rule/{rule_id}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

#### Path Parameters

- `ruleset_id` (string Id)
  The unique identifier of the query ruleset containing the rule to retrieve
- `rule_id` (string Id)
  The unique identifier of the query rule within the specified ruleset to retrieve

## Description

Get details about a query rule within a query ruleset.

## Required authorization

* Cluster privileges: `manage_search_query_rules`

[About seeing rules and rulesets](https://www.elastic.co/docs/solutions/search/query-rules-ui#accessing-the-query-rules-ui)

## Response

`application/json`

- `rule_id` (string Id)
  A unique identifier for the rule.
- `type` (enum QueryRuleType)
  The type of rule.
`pinned` will identify and pin specific documents to the top of search results.
`exclude` will exclude specific documents from search results.
  Values: `pinned`, `exclude`
- `criteria` (union oneOf)
  The criteria that must be met for the rule to be applied.
If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
  `QueryRuleCriteria` or `QueryRuleCriteria[]`
  - `type` (enum QueryRuleCriteriaType)
    The type of criteria. The following criteria types are supported:

* `always`: Matches all queries, regardless of input.
* `contains`: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.
* `exact`: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.
* `fuzzy`: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.
* `gt`: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.
* `gte`: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
* `lt`: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.
* `lte`: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.
* `prefix`: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.
* `suffix`: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.
    Values: `global`, `exact`, `fuzzy`, `prefix`, `suffix`, `contains`, `lt`, `lte`, `gt`, `gte`, `always`
  - `metadata` (string)
    The metadata field to match against.
This metadata will be used to match against `match_criteria` sent in the rule.
It is required for all criteria types except `always`.
  - `values` ([] object)
    The values to match against the `metadata` field.
Only one value must match for the criteria to be met.
It is required for all criteria types except `always`.
- `actions` ({} QueryRuleActions)
  The actions to take when the rule is matched.
The format of this action depends on the rule type.
  - `ids` ([] string Id)
    The unique document IDs of the documents to apply the rule to.
Only one of `ids` or `docs` may be specified and at least one must be specified.
  - `docs` ([] PinnedDoc)
    The documents to apply the rule to.
Only one of `ids` or `docs` may be specified and at least one must be specified.
There is a maximum value of 100 documents in a rule.
You can specify the following attributes for each document:

* `_index`: The index of the document to pin.
* `_id`: The unique document ID.
    - `_id` (string Id)
      The unique document ID.
    - `_index` (string IndexName)
      The index that contains the document.
- `priority` (number)
## Code Examples

#### Console

```console
GET _query_rules/my-ruleset/_rule/my-rule1
```

#### JavaScript

```javascript
const response = await client.queryRules.getRule({
  ruleset_id: "my-ruleset",
  rule_id: "my-rule1",
});
```

#### Python

```python
resp = client.query_rules.get_rule(
    ruleset_id="my-ruleset",
    rule_id="my-rule1",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/_query_rules/my-ruleset/_rule/my-rule1" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.queryRules().getRule(g -> g
    .ruleId("my-rule1")
    .rulesetId("my-ruleset")
);
```

#### C#

```c#
var response = await client.QueryRules.GetRuleAsync(rulesetId: "my-ruleset", ruleId: "my-rule1");
```

#### PHP

```php
$resp = $client->queryRules()->getRule([
    "ruleset_id" => "my-ruleset",
    "rule_id" => "my-rule1",
]);
```

#### Ruby

```ruby
response = client.query_rules.get_rule(
  ruleset_id: "my-ruleset",
  rule_id: "my-rule1"
)
```

## Response Examples

#### Query rule get response example1

A successful response from `GET _query_rules/my-ruleset/_rule/my-rule1`.

```json
{
  "rule_id": "my-rule1",
  "type": "pinned",
  "criteria": [
    {
      "type": "contains",
      "metadata": "query_string",
      "values": [
        "pugs",
        "puggles"
      ]
    }
  ],
  "actions": {
    "ids": [
      "id1",
      "id2"
    ]
  }
}
```