---
type: api
title: Test a Grok pattern
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-text-structure-test-grok-pattern
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-text-structure-test-grok-pattern
products:
  - Elasticsearch
---

# Test a Grok pattern


Availability: 8.13+

## Paths

- `POST` (also `GET`) `/_text_structure/test_grok_pattern`

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

## Description

Test a Grok pattern on one or more lines of text.
The API indicates whether the lines match the pattern together with the offsets and lengths of the matched substrings.

[Learn more about Grok patterns](https://www.elastic.co/docs/explore-analyze/scripting/grok)

## Query String Parameters

- `ecs_compatibility` (string · default: disabled)
  The mode of compatibility with ECS compliant Grok patterns.
Use this parameter to specify whether to use ECS Grok patterns instead of legacy ones when the structure finder creates a Grok pattern.
Valid values are `disabled` and `v1`.

## Request Body

`application/json`

- `grok_pattern` (string) — required
  The Grok pattern to run on the text.
- `text` ([] string) — required
  The lines of text to run the Grok pattern on.

## Response

`application/json`

- `matches` ([] MatchedText)
  - `matched` (boolean)
  - `fields` (map string to MatchedField)
## Code Examples

#### Console

```console
POST _text_structure/test_grok_pattern
{
  "grok_pattern": "Hello %{WORD:first_name} %{WORD:last_name}",
  "text": [
    "Hello John Doe",
    "this does not match"
  ]
}
```

#### JavaScript

```javascript
const response = await client.textStructure.testGrokPattern({
  grok_pattern: "Hello %{WORD:first_name} %{WORD:last_name}",
  text: ["Hello John Doe", "this does not match"],
});
```

#### Python

```python
resp = client.text_structure.test_grok_pattern(
    grok_pattern="Hello %{WORD:first_name} %{WORD:last_name}",
    text=[
        "Hello John Doe",
        "this does not match"
    ],
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_text_structure/test_grok_pattern" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grok_pattern": "Hello %{WORD:first_name} %{WORD:last_name}",
    "text": [
      "Hello John Doe",
      "this does not match"
    ]
  }'
```

#### Java

```java
client.textStructure().testGrokPattern(t -> t
    .grokPattern("Hello %{WORD:first_name} %{WORD:last_name}")
    .text(List.of("Hello John Doe","this does not match"))
);
```

#### C#

```c#
var response = await client.TextStructure
    .TestGrokPatternAsync(d1 => d1
        .GrokPattern("Hello %{WORD:first_name} %{WORD:last_name}")
        .Text("Hello John Doe", "this does not match")
    );
```

#### PHP

```php
$resp = $client->textStructure()->testGrokPattern([
    "body" => [
        "grok_pattern" => "Hello %{WORD:first_name} %{WORD:last_name}",
        "text" => array(
            "Hello John Doe",
            "this does not match",
        ),
    ],
]);
```

#### Ruby

```ruby
response = client.text_structure.test_grok_pattern(
  body: {
    "grok_pattern": "Hello %{WORD:first_name} %{WORD:last_name}",
    "text": [
      "Hello John Doe",
      "this does not match"
    ]
  }
)
```

## Response Examples

#### Test grok pattern response example1

A successful response from `GET _text_structure/test_grok_pattern`.

```json
{
  "matches": [
    {
      "matched": true,
      "fields": {
        "first_name": [
          {
            "match": "John",
            "offset": 6,
            "length": 4
          }
        ],
        "last_name": [
          {
            "match": "Doe",
            "offset": 11,
            "length": 3
          }
        ]
      }
    },
    {
      "matched": false
    }
  ]
}
```