Skip to main content
POST
Include a revision in analytics

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-....

Headers

Prefer
string

Send return=minimal to get no body back from a write and skip reading the resource: a create answers 201 with only Location, and an update answers 204.

Example:

"return=minimal"

Path Parameters

id
string
required

Revision ID. A metric ID answers 404; read a metric under /v2/metrics.

Minimum string length: 1
Example:

"revision_123"

Response

The included revision. The body is the resource as its GET answers it.

id
string
required

Revision ID.

Example:

"revision_123"

metricId
string
required

The metric this revision belongs to.

Example:

"metric_123"

number
integer
required

The revision number within its metric, allocated once when the revision is created and never reused. The revision shows as "R" followed by this number, so 3 is "R3".

Required range: x > 0
Example:

3

parentRevisionId
string | null
required

The revision this one was revised from. Null for the first revision of a metric.

Example:

"revision_122"

name
string | null
required

The name this revision was saved under, when it differs from its metric's name. Null otherwise: read the metric for its name.

Example:

"Accuracy (strict judge)"

isActive
boolean
required
read-only

Whether this is the active revision of its metric: its own legacy date is unset, it is not deleted and it is not being optimized.

legacyAt
string<date-time> | null
required
read-only

Earliest non-null of this revision's own legacy date and its evaluator model's unselectableAt, once that date has passed.

disabledAt
string<date-time> | null
required
read-only

Earliest non-null of the metric's disabled date and this revision's evaluator model's disabledAt.

definition
string | null
required

Name of the built-in evaluator the metric runs, for example json_field_match. Null when the metric names none.

judgePrompt
string | null
required
Example:

"Evaluate the accuracy of the response"

evaluatorModelName
string | null
required
Example:

"gpt-4"

evaluationParams
string[]
required

Ordered list of trace fields the evaluator needs, written in snake_case (e.g. input, actual_output, expected_output, retrieval_context). Determines which data the evaluation engine extracts from each trace. Full list of accepted values: https://docs.galtea.ai/concepts/metric/evaluation-parameters

Example:
areEvalParamsTop
boolean | null
required

When true, evaluationParams are injected at the top level of the evaluator prompt instead of nested inside the conversation context.

judgeGenerationSettings
object | null
required

The generation settings this metric's judge runs with. Null runs the platform defaults. Immutable: changing one creates a revision.

passThreshold
number
required

Score from 0 to 1 at or above which an evaluation of this metric passes. Immutable: changing it creates a revision.

Required range: 0 <= x <= 1
Example:

0.7

applicabilityScope
enum<string>
required

Which sessions get the applicability check before this metric is judged. NONE for a metric the platform does not score. A metric that scores only traces is never checked, so it takes NONE and refuses any other value. A metric that also scores another field is checked without traces: on each turn's input and actual output and its other fields. A FULL_PROMPT metric with empty evaluationParams whose judge prompt reads only traces is stored as checked, yet the evaluator judges it without the check. A FULL_PROMPT metric whose evaluationParams list only traces takes NONE even when its judge prompt reads another field: list that field in evaluationParams to get the check. Immutable: changing it creates a revision. The check runs only where the deployment enables it.

Available options:
NONE,
DEVELOPMENT,
PRODUCTION,
ALL
Example:

"PRODUCTION"

applicabilityThreshold
number | null
required

The lowest probability that the metric applies to a session at which it is judged. Null means the platform default, 0.5. Immutable: changing it creates a revision.

Required range: 0 <= x <= 1
Example:

0.7

classifierQuestion
object
required

The one question of a CLASSIFIER metric; null for every other source.

isBeingOptimized
boolean
required
read-only

Whether the metric is currently being optimized.

optimizationStatus
enum<string> | null
required
read-only

Where an optimization attempt stands. Null for a metric that did not come from an optimization. A candidate waiting for review is legacy until it is activated.

Available options:
OPTIMIZING,
READY_FOR_REVIEW,
FAILED,
NO_IMPROVEMENT,
DECLINED,
ACTIVATED
Example:

"READY_FOR_REVIEW"

optimizationValidation
object | null
required
read-only

How an optimization attempt was validated: the held-out evaluations and, once the optimizer reported, both prompts scored on the search rows and on the held-out rows. Set on an optimization attempt only, and null for any other metric, for an attempt that predates it, and for an attempt copied from another organization.

optimizationRun
object | null
required
read-only

What an optimization attempt ran: the strategies, the step budget and the steps used. Null while the attempt runs, and when it was not reported: an attempt from before the report existed, one run by an older optimizer, a failed run, an attempt copied from another organization, or a metric that is not an optimization attempt. Null never means a run of 0 steps.

specificationIds
string[]
required

Specifications linked to this revision. A MEMBER caller sees only the specifications of the products it can read.

Example:
userGroupIds
string[]
required

User groups of the caller's organization linked to this revision.

Example:
excludedFromAnalyticsAt
string<date-time> | null
required
read-only

When this revision was excluded from analytics. Null when its results still count. The other revisions of the metric are unaffected.

excludedByUserId
string | null
required
read-only

User who excluded this revision from analytics. A repeated exclusion keeps the first user.

createdAt
string<date-time>
required