curl --request PATCH \
--url https://api.coval.dev/v1/metrics/{metric_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"prompt": "Updated evaluation prompt"
}
'{
"metric": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "metrics/abc123def456ghi789jklm",
"id": "abc123def456ghi789jklm",
"metric_name": "Customer Satisfaction",
"description": "Evaluates customer satisfaction",
"metric_type": "METRIC_LLM_BINARY",
"create_time": "2023-11-07T05:31:56Z",
"judge_mode": "STANDARD",
"evaluation": {
"evaluator": "<string>",
"output_type": "<string>",
"output_type_source": "<string>",
"semantic_type": "<string>",
"semantic_type_source": "<string>"
},
"prompt": "Did the agent resolve the issue?",
"enabled_tools": [
"get_transcript"
],
"dependency_metric_ids": [
"<string>"
],
"categories": [
"positive",
"neutral",
"negative"
],
"min_value": 1,
"max_value": 10,
"metadata_field_type": "STRING",
"metadata_field_key": "satisfaction_score",
"regex_pattern": "(hello|hi)",
"role": "agent",
"min_pause_duration_seconds": 0.5,
"max_silence_duration_seconds": 1,
"min_silence_gap_seconds": 1,
"frequency_threshold": 1,
"direction": "above",
"success_sentiments": [
"Neutral"
],
"percent_above": 50,
"success_end_reasons": [
"UNKNOWN"
],
"observation_name": "<string>",
"expected_body": "<string>",
"match_path": "<string>",
"min_volume_change_for_pitch_misalignment": 1,
"threshold": 1,
"operator": "<",
"ivr_flow": {
"start_node": "greeting",
"nodes": [
{
"id": "greeting",
"prompt": "Welcome to Acme Support. Press 1 for sales, 2 for support."
},
{
"id": "sales",
"prompt": "Connecting you to our sales team.",
"terminal": true
},
{
"id": "support",
"prompt": "Please describe your issue after the tone.",
"terminal": true
}
],
"edges": [
{
"source": "greeting",
"destination": "sales",
"input": "1"
},
{
"source": "greeting",
"destination": "support",
"input": "2"
}
]
},
"sql_query": "SELECT start_offset_milliseconds, latency_milliseconds AS value FROM events",
"aggregation_method": "<string>",
"unit": "<string>",
"criteria_source": "test_case",
"criteria_path": "expected_behaviors",
"criteria": [
"The agent confirms the appointment time"
],
"reporting_method": "percentage_of_criteria_met",
"base_prompt_template": "<string>",
"include_traces": true,
"audio_filter": {},
"runtime_config": {
"model_version": "openai:gpt-4.1-mini-2025-04-14",
"thinking_enabled": true
},
"target_condition": {
"comparison_operator": "in",
"target_values": [
"YES"
]
},
"tags": [
"production",
"llm"
],
"update_time": "2023-11-07T05:31:56Z",
"current_version": {
"ulid": "01KKWQYSF737ZN6X1Q1RYX8M2D",
"version_number": 3,
"change_type": "save"
},
"case_insensitive": true,
"detection_preset": "<string>",
"harmonics_to_noise_ratio_threshold_offset_db": 123,
"jitter_threshold_multiplier": 123,
"loud_threshold_db": 123,
"low_pitch_threshold_multiplier": 123,
"mad_z_score_threshold": 123,
"match_mode": "presence",
"metric_attribute": "<string>",
"min_fry_segment_seconds": 123,
"organization_threshold": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"id": "01JCQR8Z9PQSTNVWXY12AB34CD",
"name": "metrics/abc123def456ghi789jklm/threshold",
"comparison_operator": "eq",
"target_float_upper": 0.8,
"target_float_lower": 123,
"target_values": [
"<string>"
],
"source": "manual",
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z"
},
"pause_detection_preset": "<string>",
"pitch_change_threshold_hz": 123,
"position": "any",
"significant_changes_threshold_hz": 123,
"soft_threshold_db": 123,
"span_name": "<string>",
"threshold_preset": "<string>",
"value_source": "<string>"
}
}Update metric
Partial update of metric fields. Only provided fields are updated.
curl --request PATCH \
--url https://api.coval.dev/v1/metrics/{metric_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"prompt": "Updated evaluation prompt"
}
'{
"metric": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"name": "metrics/abc123def456ghi789jklm",
"id": "abc123def456ghi789jklm",
"metric_name": "Customer Satisfaction",
"description": "Evaluates customer satisfaction",
"metric_type": "METRIC_LLM_BINARY",
"create_time": "2023-11-07T05:31:56Z",
"judge_mode": "STANDARD",
"evaluation": {
"evaluator": "<string>",
"output_type": "<string>",
"output_type_source": "<string>",
"semantic_type": "<string>",
"semantic_type_source": "<string>"
},
"prompt": "Did the agent resolve the issue?",
"enabled_tools": [
"get_transcript"
],
"dependency_metric_ids": [
"<string>"
],
"categories": [
"positive",
"neutral",
"negative"
],
"min_value": 1,
"max_value": 10,
"metadata_field_type": "STRING",
"metadata_field_key": "satisfaction_score",
"regex_pattern": "(hello|hi)",
"role": "agent",
"min_pause_duration_seconds": 0.5,
"max_silence_duration_seconds": 1,
"min_silence_gap_seconds": 1,
"frequency_threshold": 1,
"direction": "above",
"success_sentiments": [
"Neutral"
],
"percent_above": 50,
"success_end_reasons": [
"UNKNOWN"
],
"observation_name": "<string>",
"expected_body": "<string>",
"match_path": "<string>",
"min_volume_change_for_pitch_misalignment": 1,
"threshold": 1,
"operator": "<",
"ivr_flow": {
"start_node": "greeting",
"nodes": [
{
"id": "greeting",
"prompt": "Welcome to Acme Support. Press 1 for sales, 2 for support."
},
{
"id": "sales",
"prompt": "Connecting you to our sales team.",
"terminal": true
},
{
"id": "support",
"prompt": "Please describe your issue after the tone.",
"terminal": true
}
],
"edges": [
{
"source": "greeting",
"destination": "sales",
"input": "1"
},
{
"source": "greeting",
"destination": "support",
"input": "2"
}
]
},
"sql_query": "SELECT start_offset_milliseconds, latency_milliseconds AS value FROM events",
"aggregation_method": "<string>",
"unit": "<string>",
"criteria_source": "test_case",
"criteria_path": "expected_behaviors",
"criteria": [
"The agent confirms the appointment time"
],
"reporting_method": "percentage_of_criteria_met",
"base_prompt_template": "<string>",
"include_traces": true,
"audio_filter": {},
"runtime_config": {
"model_version": "openai:gpt-4.1-mini-2025-04-14",
"thinking_enabled": true
},
"target_condition": {
"comparison_operator": "in",
"target_values": [
"YES"
]
},
"tags": [
"production",
"llm"
],
"update_time": "2023-11-07T05:31:56Z",
"current_version": {
"ulid": "01KKWQYSF737ZN6X1Q1RYX8M2D",
"version_number": 3,
"change_type": "save"
},
"case_insensitive": true,
"detection_preset": "<string>",
"harmonics_to_noise_ratio_threshold_offset_db": 123,
"jitter_threshold_multiplier": 123,
"loud_threshold_db": 123,
"low_pitch_threshold_multiplier": 123,
"mad_z_score_threshold": 123,
"match_mode": "presence",
"metric_attribute": "<string>",
"min_fry_segment_seconds": 123,
"organization_threshold": {
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"id": "01JCQR8Z9PQSTNVWXY12AB34CD",
"name": "metrics/abc123def456ghi789jklm/threshold",
"comparison_operator": "eq",
"target_float_upper": 0.8,
"target_float_lower": 123,
"target_values": [
"<string>"
],
"source": "manual",
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z"
},
"pause_detection_preset": "<string>",
"pitch_change_threshold_hz": 123,
"position": "any",
"significant_changes_threshold_hz": 123,
"soft_threshold_db": 123,
"span_name": "<string>",
"threshold_preset": "<string>",
"value_source": "<string>"
}
}Authorizations
API key for authentication
Headers
Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.
1 - 26Path Parameters
22-character metric ID
^[a-zA-Z0-9]{22}$Body
Update metric request (partial update)
1 - 2001 - 1000Metric evaluation type.
METRIC_AGENT_JUDGE- Agentic binary evaluation with bounded evidence toolsMETRIC_AGENT_JUDGE_CATEGORICAL- Agentic categorical evaluation with bounded evidence toolsMETRIC_AGENT_JUDGE_NUMERICAL- Agentic numerical evaluation with bounded evidence toolsMETRIC_LLM_BINARY- Yes/no LLM evaluationMETRIC_CATEGORICAL- Multi-class classificationMETRIC_NUMERICAL_LLM_JUDGE- Numerical scoring (1-N)METRIC_AUDIO_LLM_BINARY- Audio-based yes/noMETRIC_AUDIO_LLM_CATEGORICAL- Audio-based classificationMETRIC_AUDIO_LLM_NUMERICAL- Audio-based scoringMETRIC_TOOLCALL- Tool/function call evaluationMETRIC_METADATA_FIELD- Extract metadata fieldMETRIC_TRANSCRIPT_REGEX- Regex pattern matchingMETRIC_PAUSE_ANALYSIS- Speech pause detectionMETRIC_SQL_FLOAT- Custom SQL query over the simulation's data (setsql_query)METRIC_COMPOSITE_EVALUATION- Judges a list of criteria independently and reports how many were met (setcriteria_source, andcriteria_pathorcriteriato match)
METRIC_LLM_BINARY, METRIC_AGENT_JUDGE, METRIC_AGENT_JUDGE_CATEGORICAL, METRIC_CATEGORICAL, METRIC_AUDIO_LLM_BINARY, METRIC_AUDIO_LLM_CATEGORICAL, METRIC_TOOLCALL, METRIC_METADATA_FIELD, METRIC_AGENT_JUDGE_NUMERICAL, METRIC_NUMERICAL_LLM_JUDGE, METRIC_AUDIO_LLM_NUMERICAL, METRIC_TRANSCRIPT_REGEX, METRIC_USER_FRUSTRATION, METRIC_AGENT_REFUSAL, METRIC_PAUSE_ANALYSIS, METRIC_SQL_FLOAT, METRIC_COMPOSITE_EVALUATION, METRIC_LLM_TTFB, METRIC_TTS_TTFB, METRIC_STT_TTFB, METRIC_LLM_TOKEN_USAGE, METRIC_TOOL_CALL_RATE, METRIC_TRACE_STT_WER, METRIC_TRACE_AUDIO_UPLOAD_STT_WER, METRIC_CUSTOM_TRACE, METRIC_VOICE_QUALITY, METRIC_PHONEME_STRETCH, METRIC_SYLLABLE_RATE, METRIC_LOOP_DETECTION, METRIC_CODEC_ARTIFACT, METRIC_CLIPPING_ARTIFACT, METRIC_DROPOUT_ARTIFACT, METRIC_TIMBRE_DRIFT, METRIC_SPEECH_ARTIFACT_ANOMALY, METRIC_PITCH_VARIABILITY, METRIC_NON_EXPRESSIVE_PAUSES, METRIC_ABRUPT_PITCH_CHANGES, METRIC_TERMINAL_CONTOUR, METRIC_LUFS, METRIC_VOLUME, METRIC_VOCAL_FRY, METRIC_DERIVED_STRICT_LOGIC, METRIC_DERIVED_AGGREGATE, METRIC_IVR_FLOW_ADHERENCE, METRIC_CUSTOM_AGENT_FAILS_TO_RESPOND, METRIC_CUSTOM_AGENT_NEEDS_REPROMPTING, METRIC_CUSTOM_AUDIO_FREQUENCY, METRIC_CUSTOM_AUDIO_SENTIMENT, METRIC_CUSTOM_END_REASON, METRIC_MATCH_EXPECTED_OUTPUT, METRIC_SPEAKING_TIME_PERCENTAGE, METRIC_SPECTROGRAM_PITCH_ANALYSIS, METRIC_VOLUME_PITCH_MISALIGNMENT, METRIC_WORDS_PER_MESSAGE_WITH_THRESHOLD LLM Judge execution mode. Omit to preserve the existing mode.
STANDARD, AGENTIC Agentic LLM Judge tools. Omit to preserve the current/default selection; pass [] to disable all tools.
Evidence tool available to an Agent Judge metric.
get_transcript, search_transcript, search_transcript_regex, get_trace_spans, query_simulation_frames, get_run_context, get_evidence_manifest, get_simulation_outcome, get_dependency_metric_outputs Agent Judge metric dependencies. Omit to preserve the saved value; pass [] to clear dependencies.
1012 - 50 elementsData type for metadata field extraction
STRING, NUMBER, BOOLEAN agent, persona, user, assistant x >= 0.5x > 0x > 0x > 0above, below 1Neutral, Happy, Angry, Sad 0 <= x <= 1001UNKNOWN, IDLE_TIMEOUT, DURATION_LIMIT, PERSONA_DISCONNECTED, AGENT_DISCONNECTED, PIPELINE_ERROR, REPETITION_LOOP, AUDIO_UPLOAD_PLAYBACK_COMPLETED, SCRIPT_COMPLETED, SCRIPT_DIVERGED 11Optional dot path; brackets must contain an integer index or comma-separated key=value filters.
1x > 0x >= 0<, <=, >, >=, ==, != IVR flow definition (for METRIC_IVR_FLOW_ADHERENCE). Explicit null clears it.
Show child attributes
Show child attributes
{
"start_node": "greeting",
"nodes": [
{
"id": "greeting",
"prompt": "Welcome to Acme Support. Press 1 for sales, 2 for support."
},
{
"id": "sales",
"prompt": "Connecting you to our sales team.",
"terminal": true
},
{
"id": "support",
"prompt": "Please describe your issue after the tone.",
"terminal": true
}
],
"edges": [
{
"source": "greeting",
"destination": "sales",
"input": "1"
},
{
"source": "greeting",
"destination": "support",
"input": "2"
}
]
}
SQL query that defines the metric (for METRIC_SQL_FLOAT). SQL unit values must
use supported result-unit identifiers such as s, ms, or count. An omitted
unit preserves the current value; null or an empty string clears it.
50000Aggregation method for custom trace values, or SUM, AVERAGE, MIN, MAX, or COUNT for METRIC_SQL_FLOAT. Omit to preserve the current method; null resets a SQL metric to AVERAGE.
Optional display unit. For METRIC_SQL_FLOAT, use a result-unit identifier such as s, ms, count, or percent. Omit to preserve the current unit; null or an empty string clears it.
32Where a METRIC_COMPOSITE_EVALUATION metric reads its criteria from.
test_case, test_case_attribute, metric_metadata Path to the criteria on the source, when criteria_source is test_case
or test_case_attribute.
200Literal list of criteria, when criteria_source is metric_metadata.
How per-criterion verdicts aggregate into the metric's value.
percentage_of_criteria_met, count_of_criteria_met, all_criteria_met Custom prompt template used to evaluate each criterion.
50000Inject OTel trace context into the LLM judge prompt during evaluation.
Supported for LLM judge metric types and METRIC_COMPOSITE_EVALUATION.
Omit to keep the current filter. null removes it so the metric analyzes its default scope. Any other
value replaces the current filter. Supported for METRIC_ABRUPT_PITCH_CHANGES, METRIC_AUDIO_LLM_BINARY, METRIC_AUDIO_LLM_CATEGORICAL, METRIC_AUDIO_LLM_NUMERICAL, METRIC_CLIPPING_ARTIFACT, METRIC_CODEC_ARTIFACT, METRIC_CUSTOM_AGENT_NEEDS_REPROMPTING, METRIC_CUSTOM_AUDIO_FREQUENCY, METRIC_CUSTOM_AUDIO_SENTIMENT, METRIC_DROPOUT_ARTIFACT, METRIC_LOOP_DETECTION, METRIC_LUFS, METRIC_NON_EXPRESSIVE_PAUSES, METRIC_PAUSE_ANALYSIS, METRIC_PHONEME_STRETCH, METRIC_PITCH_VARIABILITY, METRIC_SPEAKING_TIME_PERCENTAGE, METRIC_SPECTROGRAM_PITCH_ANALYSIS, METRIC_SPEECH_ARTIFACT_ANOMALY, METRIC_SYLLABLE_RATE, METRIC_TERMINAL_CONTOUR, METRIC_TIMBRE_DRIFT, METRIC_VOCAL_FRY, METRIC_VOICE_QUALITY, METRIC_VOLUME, METRIC_VOLUME_PITCH_MISALIGNMENT; rejected with 400 for any other type.
Changing metric_type to an unsupported type removes the filter.
Show child attributes
Show child attributes
{
"include": [
{
"type": "speaker",
"speakers": ["persona"]
}
]
}
Override the LLM model used for metric evaluation. Set to null to revert to
the platform default. Use GET /v1/models/metric to list available models.
Not supported for audio metric types (METRIC_AUDIO_LLM_BINARY,
METRIC_AUDIO_LLM_CATEGORICAL, METRIC_AUDIO_LLM_NUMERICAL),
which always use the platform-default audio model.
Show child attributes
Show child attributes
Target condition for metric evaluation
- Option 1
- Option 2
Show child attributes
Show child attributes
{
"comparison_operator": "in",
"target_values": ["YES"]
}
Tags to associate with this metric. Null or omitted leaves tags unchanged. Pass [] to clear all tags.
["production"]
Apply case-insensitive matching
METRIC_ABRUPT_PITCH_CHANGES / METRIC_NON_EXPRESSIVE_PAUSES / METRIC_VOCAL_FRY preset: 'strict', 'normal', or 'lenient'.
strict, normal, lenient Advanced (dB): offset below baseline HNR under which a frame is fry (less negative flags more).
-25 <= x < 0Advanced: multiple of baseline jitter above which a frame is fry (lower flags more).
x > 1Advanced (dBFS): level at/above which audio is flagged loud. Must exceed soft_threshold_db.
-60 <= x <= 0Advanced: pitch fraction of baseline below which a frame is fry (higher flags more).
0 < x < 1Advanced: override the preset's MAD modified z-score threshold.
x > 0Match mode: 'presence' or 'absence'
presence, absence Span attribute key to measure
200Derived metric config (replaces existing config on update)
Advanced (s): minimum kept fry-run duration (lower flags more).
0 <= x <= 1Anomaly detection preset (recommended). 'strict' / 'normal' / 'lenient' control MAD threshold and minimum pause count. Most callers should set this instead of the fields below.
strict, normal, lenient Advanced (Hz): pitch movement near a pause above which the pause counts as expressive.
x > 0Position constraint: 'any', 'first', or 'last'
any, first, last Advanced (Hz): pitch jump above which a change counts as abrupt (lower flags more).
x > 0Advanced (dBFS): level at/below which audio is flagged soft.
-60 <= x <= 0OTel span name to query
200METRIC_VOLUME threshold preset: 'strict', 'normal', or 'lenient'.
strict, normal, lenient Source of the aggregated value for METRIC_CUSTOM_TRACE: 'attribute' reads the configured span attribute; 'duration' aggregates the span's own duration in seconds. None leaves it unchanged.
Response
Metric updated
Metric resource
Show child attributes
Show child attributes
Was this page helpful?