stores

Match store chunks against a regular expression

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 matches across all requested stores and returns at most top_k chunks in total. Matches are unranked and interleaved across stores in the order requested, preserving each store's result order. Pagination is not supported; 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: IDs or names of the stores 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

post/v1/stores/grep

Headers

X-Mxbai-Tool-Ticketstring nullable

Ticket from a chat completion's tool_tickets, proving this call runs a tool call that completion asked for. Redeems once, and bills the operation at the discounted agent rate.

Request body

top_kinteger

Number of results to return

file_idsstring[] nullable

Optional list of file IDs to filter chunks by (inclusion filter)

patternstring required

Regular expression (RE2 syntax) matched against chunk text

targetsStoreChunkGrepTarget[]

Chunk content groups to match against. text matches the original text of text chunks; generated matches ingestion-derived fields (transcription, OCR text, summaries).

case_sensitiveboolean

Whether the regular expression is case-sensitive

return_metadataboolean

Whether to return file metadata

Example request

{
  "filters": {
    "all": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ],
    "any": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ],
    "none": [
      {
        "key": "price",
        "operator": "gt",
        "value": "100"
      },
      {
        "key": "color",
        "operator": "eq",
        "value": "red"
      }
    ]
  },
  "file_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "pattern": "ERR-\\d{4}"
}

Response

List of chunks whose text matches the pattern

object'list'

The object type of the response

Example response

{
  "data": [
    {
      "mime_type": "text/plain",
      "model": "text-embedding-ada-002",
      "score": 0.5,
      "file_id": "file1",
      "filename": "file1",
      "store_id": "store1",
      "external_id": "ext-123",
      "metadata": {
        "key": "value"
      },
      "context": "This chunk is from an SEC filing on ACME corp's Q2 2023 performance.",
      "summary": "A short overview of ACME's Q2 2023 performance."
    }
  ]
}

Changes

Changed in 4 of the 30 revisions of this API.418

Sep 15, 2026957bf8ec8df844See the full diff
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //// response property oneOf list for the response status
  response-property-one-of-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
- ○
  added csv discriminator mapping keys to the //// response property for the response status
  response-property-discriminator-mapping-added
Sep 8, 2026ce403656bc181See the full diff
- ●
  the request property's max was set to 10000.00
  request-property-max-set
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 14, 2026e5ddc69af9411See the full diff
- ○
  added the new optional header request parameter X-Mxbai-Tool-Ticket
  new-optional-request-parameter
Jul 26, 2026587cbdf607b03See the full diff
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history