Preview monitor content-filter matches

Read-only preview for a CANDIDATE monitor config: how many and which recent past sessions the given content filter, message conditions and sampling percentage would select, among the most recent closed production sessions inside a look-back window. Runs no evaluations, spends no credits, and writes nothing (no processed marks). Use it while creating or editing a monitor. The match count is exact; for a create preview (no monitorId) the sampled subset is representative, not the exact set the created monitor will draw. With metricGroupIds or specificationIds, it also answers the credits one evaluated session costs.

POST /monitors/preview

Preview monitor content-filter matches

cURL

curl --request POST \
  --url https://api.galtea.ai/monitors/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "productId": "prod_123",
  "samplingPercentage": 10,
  "versionId": "version_123",
  "filterQuery": "refund",
  "filterTarget": "EITHER",
  "excludeQuery": "test, internal",
  "excludeTarget": "EITHER",
  "messageConditions": [
    {
      "count": "messages",
      "operator": "gt",
      "value": 1
    }
  ],
  "days": 90,
  "monitorId": "monitor_123",
  "metricGroupIds": [
    "metricGroup_123"
  ],
  "specificationIds": [
    "specification_123"
  ]
}
'

200

{
  "range": {
    "from": "2023-11-07T05:31:56Z",
    "to": "2023-11-07T05:31:56Z"
  },
  "candidateCount": 500,
  "readRange": {
    "from": "2023-11-07T05:31:56Z",
    "to": "2023-11-07T05:31:56Z"
  },
  "candidateLimit": 500,
  "candidateLimitReached": false,
  "withTurnsCount": 480,
  "contentFilterMatchCount": 150,
  "matchCount": 120,
  "sampledCount": 12,
  "approximateSampling": true,
  "creditsPerSession": 4,
  "sampledSessions": [
    {
      "sessionId": "session_123",
      "versionId": "version_123",
      "createdAt": "2023-11-07T05:31:56Z",
      "turnCount": 4,
      "matchedText": "I would like a refund for my last order because it arrived damaged…"
    }
  ]
}

Authorizations

Authorization · string · header · required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json

productId · string · required

Product whose recent production sessions the preview scans.

Minimum string length: 1

Example:

"prod_123"

samplingPercentage · number · required

Candidate sampling percentage (greater than 0, at most 100).

Required range: 0 < x <= 100

Example:

10

versionId · string | null

Optional version to narrow the preview to. Null previews the whole product.

Example:

"version_123"

filterQuery · string | null

Candidate content filter. Null keeps every session that meets the message conditions.

Maximum string length: 500

Example:

"refund"

filterTarget · enum<string> | null

Which side of a turn filterQuery matches against. Set together with filterQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

excludeQuery · string | null

Candidate exclude filter. Comma-separated terms; a session is dropped when a turn whose chosen target (excludeTarget) contains ANY term. Null excludes nothing. Set together with excludeTarget. Independent of filterQuery.

Maximum string length: 500

Example:

"test, internal"

excludeTarget · enum<string> | null

Which side of a turn excludeQuery matches against. Set together with excludeQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

messageConditions · object[]

Candidate message conditions, joined by AND. Omitted previews the default (messages above 1); [] previews no message filter. A list no session can meet is refused, such as messages above 5 with messages at most 3, or more user messages than the messages allow: messages counts the user messages too.

Maximum array length: 10

Show child attributes

Example:

[
  {
    "count": "messages",
    "operator": "gt",
    "value": 1
  }
]

days · integer · default: 90

Look-back window in days that bounds which sessions are read (default 90, max 90).

Required range: 1 <= x <= 90

Example:

90

monitorId · string | null

Existing monitor id when previewing an EDIT, so sampling uses its real seed (exact). Omit for a create preview (representative sampling).

Example:

"monitor_123"

metricGroupIds · string[]

The metric families picked on the candidate monitor, as on create. Set it or specificationIds to receive creditsPerSession; omit both when you do not need the cost. A family that has no current metric, or whose metrics belong to another organization, counts 0.

Example:

["metricGroup_123"]

specificationIds · string[]

The Specifications bound to the candidate monitor, as on create. The cost counts each family they bring that can score production sessions, and a family that is also in metricGroupIds once.

Example:

["specification_123"]

Response

200

application/json

Preview computed successfully

range · object · required

The requested look-back window.

Show child attributes

candidateCount · integer · required

Recent closed production sessions considered (bounded by the window and an internal cap).

Example:

500

readRange · object | null · required

Oldest and newest creation time of the sessions actually read. Null when no session was read.

Show child attributes

candidateLimit · integer · required

The most sessions the preview reads.

Example:

500

candidateLimitReached · boolean · required

True when the preview read candidateLimit sessions, so older sessions inside the window were not read.

Example:

false

withTurnsCount · integer · required

Sessions read that hold at least one turn. The scanner never evaluates a session with no turn.

Example:

480

contentFilterMatchCount · integer · required

Sessions with at least one turn whose content filter passes. Equals withTurnsCount when no content filter is set.

Example:

150

matchCount · integer · required

Sessions that met the message conditions and matched the candidate filter (exact; a null filter keeps every session that meets the message conditions).

Example:

120

sampledCount · integer · required

Matched sessions that also fell in the sampling fraction.

Example:

12

approximateSampling · boolean · required

True for a create preview (no monitorId): the sampled subset is representative, computed from a placeholder seed. The match count is always exact.

Example:

true

creditsPerSession · integer | null · required

Credits that scoring one evaluated session costs, at the current price, for the families metricGroupIds and specificationIds give, as the scanner charges them. A metric that costs nothing (Self-Hosted, Human Evaluation, or disabled) counts 0, so empty lists cost 0. Null when the request omits both metricGroupIds and specificationIds.

Example:

4

sampledSessions · object[] · required

The would-be-selected sessions, most-recent first (capped at 100).

Show child attributes