---
title: "Match store chunks against a regular expression"
method: POST
path: "/v1/stores/grep"
tags: ["stores"]
---

# Match store chunks against a regular expression

`POST /v1/stores/grep`

Match store chunks against a regular expression.

Unlike `/stores/search`, this runs your regex against the literal text of each
chunk. Use it to find chunks containing a specific token, identifier, error code,
or literal phrase.

grep targets a single store and does not support pagination; raise `top_k` to
retrieve more matches.

Args:
    grep_params: Grep configuration including:
        - pattern: RE2 regular expression matched against chunk text
        - targets: chunk content groups to match (`text`, `generated`)
        - case_sensitive: whether the pattern is case-sensitive
        - store_identifiers: the single store to grep
        - file_ids: optional list of file IDs to filter chunks by
        - filters: optional metadata filter conditions
        - top_k: number of matches to return

Returns:
    StoreGrepResponse containing the list of matching chunks.

Raises:
    HTTPException (400): If grep parameters are invalid
    HTTPException (404): If the store is not found

## Request body

- StoreChunkGrepParams — Parameters for matching store chunks against a regular expression. Unlike semantic search, grep runs your regex against the literal text of each chunk. It finds chunks whose text matches the pattern.
  - `store_identifiers` union[], required — IDs or names of stores
    - union
      - string
      - string, uuid
  - `top_k` integer — Number of results to return
  - `filters` union — Optional filter conditions
    - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
      - `all` union[], nullable — List of conditions or filters to be ANDed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `any` union[], nullable — List of conditions or filters to be ORed together
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
      - `none` union[], nullable — List of conditions or filters to be NOTed
        - union
          - SearchFilterInput — recursive
          - SearchFilterCondition — Represents a condition with a field, operator, and value.
            - `key` string, required — The field to apply the condition on
            - `value` string, required — The value to compare against
            - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - SearchFilterCondition — Represents a condition with a field, operator, and value.
      - `key` string, required — The field to apply the condition on
      - `value` string, required — The value to compare against
      - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
    - union[]
      - union
        - SearchFilterInput — Represents a filter with AND, OR, and NOT conditions.
          - `all` union[], nullable — List of conditions or filters to be ANDed together
            - union
              - …
          - `any` union[], nullable — List of conditions or filters to be ORed together
            - union
              - …
          - `none` union[], nullable — List of conditions or filters to be NOTed
            - union
              - …
        - SearchFilterCondition — Represents a condition with a field, operator, and value.
          - `key` string, required — The field to apply the condition on
          - `value` string, required — The value to compare against
          - `operator` 'eq' | 'not_eq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'contains' | 'starts_with' | 'not_like' | 'regex', required — Operator for a filter condition.
  - `file_ids` string[], nullable — Optional list of file IDs to filter chunks by (inclusion filter)
  - `pattern` string, required — Regular expression (RE2 syntax) matched against chunk text
  - `targets` StoreChunkGrepTarget[] — Chunk content groups to match against. `text` matches the original text of text chunks; `generated` matches ingestion-derived fields (transcription, OCR text, summaries).
  - `case_sensitive` boolean — Whether the regular expression is case-sensitive
  - `return_metadata` boolean — Whether to return file metadata

## Response `200`

List of chunks whose text matches the pattern

- StoreGrepResponse
  - `object` 'list' — The object type of the response
  - `data` union[], required — The list of chunks matching the pattern
    - union
      - MxbaiOmniCoreStoreModelsChunkTypesScoredTextInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'text' — Input type identifier
        - `offset` integer — The offset of the text in the file relative to the start of the file.
        - `text` string, nullable — Text content
        - `context` string, nullable — LLM-generated context that situates this chunk within its source document
        - `summary` string, nullable — summary of the text chunk
      - MxbaiOmniCoreStoreModelsChunkTypesScoredImageUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'image_url' — Input type identifier
        - `ocr_text` string, nullable — ocr text of the image
        - `context` string, nullable — LLM-generated context that situates this image within its source document
        - `summary` string, nullable — summary of the image
        - `image_url` ImageUrlOutput — Model for image URL validation.
          - `url` string, required — The image URL. Can be either a URL or a Data URI.
          - `format` string — The image format/mimetype
      - MxbaiOmniCoreStoreModelsChunkTypesScoredAudioUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'audio_url' — Input type identifier
        - `transcription` string, nullable — speech recognition (sr) text of the audio
        - `context` string, nullable — LLM-generated context that situates this audio chunk within its source file
        - `summary` string, nullable — summary of the audio
        - `audio_url` AudioUrl — Model for audio URL validation.
          - `url` string, required — The audio URL. Can be either a URL or a Data URI.
        - `sampling_rate` integer, required — The sampling rate of the audio.
      - MxbaiOmniCoreStoreModelsChunkTypesScoredVideoUrlInputChunk
        - `chunk_index` integer, required — position of the chunk in a file
        - `mime_type` string — mime type of the chunk
        - `generated_metadata` union — metadata of the chunk
          - MarkdownChunkGeneratedMetadata
            - `type` 'markdown'
            - `file_type` 'text/markdown'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `chunk_headings` MarkdownHeading[]
              - …
            - `heading_context` MarkdownHeading[]
              - …
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
            - `frontmatter` object
          - TextChunkGeneratedMetadata
            - `type` 'text'
            - `file_type` 'text/plain' | 'message/rfc822'
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - PDFChunkGeneratedMetadata
            - `type` 'pdf'
            - `file_type` 'application/pdf'
            - `total_pages` integer, nullable
            - `total_size` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
          - CodeChunkGeneratedMetadata
            - `type` 'code'
            - `file_type` string, required
            - `language` string, nullable
            - `word_count` integer, nullable
            - `file_size` integer, nullable
            - `start_line` integer
            - `num_lines` integer
            - `file_extension` string, nullable
          - AudioChunkGeneratedMetadata
            - `type` 'audio'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `sample_rate` integer, nullable
            - `channels` integer, nullable
            - `audio_format` integer, nullable
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - VideoChunkGeneratedMetadata
            - `type` 'video'
            - `file_type` string
            - `file_size` integer, nullable
            - `total_duration_seconds` number, nullable
            - `fps` number, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `frame_count` integer, nullable
            - `has_audio_stream` boolean
            - `bpm` integer, nullable
            - `file_extension` string, nullable
          - ImageChunkGeneratedMetadata
            - `type` 'image'
            - `file_type` string
            - `file_size` integer, nullable
            - `width` integer, nullable
            - `height` integer, nullable
            - `file_extension` string, nullable
            - `layout` LayoutMetadata — Per-page layout for chunks parsed in high-quality (visual) mode. ``elements`` are ordered by reading order (list position == reading order). ``width``/``height`` are the page-image dimensions the ``bbox`` coords are relative to, so consumers can normalize/render without a second fetch. Layout is part of the generated metadata payload and is returned with the chunk whenever present.
              - …
        - `model` string, nullable — model used for this chunk
        - `score` number, required — score of the chunk
        - `file_id` string, required — file id
        - `filename` string, required — filename
        - `store_id` string, required — store id
        - `external_id` string, nullable — external identifier for this file
        - `metadata` unknown
        - `type` 'video_url' — Input type identifier
        - `transcription` string, nullable — speech recognition (sr) text of the video
        - `context` string, nullable — LLM-generated context that situates this video chunk within its source file
        - `summary` string, nullable — summary of the video
        - `video_url` VideoUrl — Model for video URL validation.
          - `url` string, required — The video URL. Can be either a URL or a Data URI.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mixedbread/apis/mxbai-omni.md) · [All operations](https://skmtc.net/mixedbread/apis/mxbai-omni/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixedbread/mxbai-omni/revisions/2eece97b5ae5/schema)