Get a group's health
const url = 'https://example.com/MIDWATER_BASE_URL/v1/groups/front-desk/health';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/MIDWATER_BASE_URL/v1/groups/front-desk/health \ --header 'Authorization: Bearer <token>'The worst status among the group’s active agents, each agent’s status, and totals across them, in the key’s environment.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A letter or digit, then up to 127 letters, digits, ., _, : or -. No /, so IDs never need URL-encoding.
Responses
Section titled “Responses”The group’s health.
object
not_enough_calls: fewer than 5 calls with an outcome in the last 7 days, so nothing is measured yet, unless a high-severity compliance failure puts the agent in watch (1) or at_risk (2 or more).
Watch and at risk name the agent that set the status.
object
not_enough_calls: fewer than 5 calls with an outcome in the last 7 days, so nothing is measured yet, unless a high-severity compliance failure puts the agent in watch (1) or at_risk (2 or more).
object
Conversations received in the window.
Conversations with an outcome (customer calls that were scored).
Share of conversations with an outcome that were resolved.
Share handed to a person (a transfer, or a person requested and provided).
Conversations where the caller asked for a person and didn’t get one.
Average caller frustration, 0 (calm) to 1 (very frustrated).
Compliance checks that failed in the window.
object
Conversations received in the window.
Conversations with an outcome (customer calls that were scored).
Share of conversations with an outcome that were resolved.
Share handed to a person (a transfer, or a person requested and provided).
Conversations where the caller asked for a person and didn’t get one.
Average caller frustration, 0 (calm) to 1 (very frustrated).
Compliance checks that failed in the window.
Examples
A group set by its worst agent
{ "group_id": "brightsmile-dental", "name": "BrightSmile Dental", "environment": "live", "health_status": "watch", "reason": "Front desk: resolution 81% vs 87% 30-day baseline (−6 pts) since version 3.2.0", "agents": [ { "id": "front-desk", "name": "Front desk", "health_status": "watch" }, { "id": "after-hours", "name": "After hours", "health_status": "healthy" } ], "last_7_days": { "conversations": 301, "with_outcome": 255, "resolution_rate": 0.83, "handed_to_person_rate": 0.08, "requests_for_person_not_honored": 2, "avg_frustration": 0.21, "compliance_failures": 0 }, "last_30_days": { "conversations": 1270, "with_outcome": 1088, "resolution_rate": 0.87, "handed_to_person_rate": 0.08, "requests_for_person_not_honored": 6, "avg_frustration": 0.19, "compliance_failures": 1 }}Headers
Section titled “Headers”Example
req_8Jx2kQ4mT9The request’s ID, also in error bodies as error.request_id. Quote it when contacting support.
Missing, malformed, unknown or revoked API key.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "authentication_error", "message": "Missing or invalid API key. Use Authorization: Bearer mw_test_… or mw_live_…" }}The key is valid but not allowed to do this.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "permission_denied", "message": "This key can't do that", "request_id": "req_8Jx2kQ4mT9" }}Not found in the key’s environment.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "not_found", "message": "Conversation not found" }}The path exists but doesn’t support this method. Allow lists the methods it does support.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "method_not_allowed", "message": "GET isn't supported here; use POST", "request_id": "req_8Jx2kQ4mT9" }}Headers
Section titled “Headers”Example
POSTThe methods the path supports, e.g. POST.
Too many requests. Wait Retry-After seconds. The limits are published when they’re set.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "rate_limited", "message": "Too many requests", "request_id": "req_8Jx2kQ4mT9" }}Headers
Section titled “Headers”Seconds to wait before retrying.
Requests allowed in the current window. The numbers are published when the limits are set.
Requests left in the current window.
Seconds until the window resets.
Something went wrong on Midwater’s side. Safe to retry with the same Idempotency-Key.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "server_error", "message": "Something went wrong on our side" }}Midwater is briefly unavailable. Retry with backoff, honouring Retry-After when present.
object
object
Stable machine-readable type. Each has a set status: invalid_json 400, authentication_error 401,
permission_denied 403, not_found 404, method_not_allowed 405, idempotency_conflict 409, payload_too_large 413,
validation_error 422, rate_limited 429, server_error 500, service_unavailable 503.
Types not yet returned are planned. Treat a type you don’t know by its status class.
Human-readable; may change.
Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.
object
The request’s ID, the same as the Midwater-Request-Id header.
Example
{ "error": { "type": "service_unavailable", "message": "Midwater is briefly unavailable", "request_id": "req_8Jx2kQ4mT9" }}Headers
Section titled “Headers”Seconds to wait before retrying.