---
title: "Apply masks to samples"
method: POST
path: "/v1/masking/mask"
tags: ["Masking"]
---

# Apply masks to samples

`POST /v1/masking/mask`

## Request

- Base URL: `https://docs.grepr.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.grepr.ai/v1/masking/mask`
- Auth: one of:
  - API key in header `GREPR-API-KEY`
  - OpenID Connect (`https://grepr-prod.us.auth0.com/.well-known/openid-configuration`)

Applies a masking operator's masks to sample log events and returns the masked result for each, so the editor can preview a configuration without deploying it. The operator's predicate gates which logs are masked in production, not how, so it is ignored here and the masks are applied to every sample.

## Request body

- MaskingRequest
  - `masking` MaskingOperator, required
    - `attributeMasks` AttributeMask[], required: Masks to apply to attribute values. Each entry names an attribute path (as a list of segments) and the masks to apply to the value at that path. Only string values at the exact path are masked; missing or non-string attributes are skipped. Paths must be unique. The same matching rules as messageMasks apply.
      - `masks` object, required: Masks to apply to the value at this path, as a map of label to mask. The same matching rules as messageMasks apply.
      - `path` string[], required: Attribute path to mask, as a list of segments.
    - `messageMasks` object, required: Masks to apply to the log message, as a map of label to mask. A mask may be written as a bare regex string, in which case each match is replaced with the label in square brackets — a match of the regex labeled "email" becomes "[email]". Labels may be up to 64 characters. Overlapping matches resolve to the leftmost match first, then the longest; declaration order breaks remaining ties, so declare more specific patterns first.
    - `name` string, required
    - `predicate` union: Predicate applied to rows before analytical aggregation.
      - object
        - `queries` EventPredicate[], required: List of predicates that must all match for this predicate to match.
        - `type` 'and-predicate', required: A predicate that matches when every child predicate matches.
        - `query` string
      - object
        - `query` string, required: The datadog query used by the predicate. See https://docs.datadoghq.com/tracing/trace_explorer/query_syntax
        - `type` 'datadog-query', required: A predicate that checks if an event matches a datadog query.
      - object
        - `filterTags` object: The set of tags to query for. If unspecified, all tags are queried.
        - `metricNames` string[], required: The names of the metrics to query. Must not be empty.
        - `query` string, required
        - `type` 'metric-predicate', required: A predicate that checks if an event matches a metrics query.
      - object
        - `query` string, required: The New Relic query used by the predicate. See https://docs.newrelic.com/docs/logs/ui-data/query-syntax-logs/
        - `type` 'newrelic-query', required: A predicate that checks if an event matches a New Relic query.
      - object
        - `query` string, required: The Nrql query used by the predicate. See https://docs.newrelic.com/docs/nrql
        - `strict` boolean: Whether the query should be parsed in strict mode.
        - `type` 'nrql-query', required: A predicate that checks if an event matches an NRQL query.
    - `type` 'masking-operator', required: Masks sensitive substrings in log events by replacing regex matches with decorated labels.
  - `samples` MaskingSample[], required: The sample log events to apply the masks to.
    - `attributes` object, required: Sample attributes the attribute masks are applied to.
    - `message` string: Sample log message the masks are applied to. May be omitted to test attribute masks alone.

## Response `200`

Sample masked successfully.

- MaskingResponse
  - `results` MaskingResult[], required: The masked results, aligned by position with the request's samples.
    - `maskedAttributes` object, required: The sample attributes after masking, unchanged when no mask matched.
    - `maskedCount` integer: The number of substrings replaced across the message and attributes; zero when nothing matched.
    - `maskedMessage` string: The sample message after masking, unchanged when no mask matched.

## Other responses

- `400`: The masking configuration is invalid or could not be compiled.
- `401`: Unauthorized

---

[API](https://skmtc.dev/grepr/apis/grepr-api.md) - [All operations](https://skmtc.dev/grepr/apis/grepr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/grepr/apis/grepr-api/revisions/2a5ce03a0bf0?raw)