Skip to content
MidwaterDocs

Get an agent's health

GET
/v1/agents/{agent_id}/health
curl --request GET \
  --url https://example.com/MIDWATER_BASE_URL/v1/agents/front-desk/health \
  --header 'Authorization: Bearer <token>'

The agent’s health in the key’s environment, with 7- and 30-day windows. agent_id is the agent.id you send (or default).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agent_id
required

A letter or digit, then up to 127 letters, digits, ., _, : or -. No /, so IDs never need URL-encoding.

string
/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/

Responses

Section titled “Responses”

200

Section titled “200”

The agent’s health.

Media typeapplication/json
object
agent_id
required
string
name
required
string
environment
required

The key’s environment; health is measured per environment.

string
Allowed values: test live
health_status
required

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

string
Allowed values: healthy watch at_risk not_enough_calls
reason
required

Why, in one sentence, e.g. “Needs 4 more calls with an outcome this week”.

string
group
required
object
id
required
string
name
required
string
last_7_days
required
object
conversations
required

Conversations received in the window.

integer
with_outcome
required

Conversations with an outcome (customer calls that were scored).

integer
resolution_rate
required

Share of conversations with an outcome that were resolved.

number | null
handed_to_person_rate
required

Share handed to a person (a transfer, or a person requested and provided).

number | null
requests_for_person_not_honored
required

Conversations where the caller asked for a person and didn’t get one.

integer
avg_frustration
required

Average caller frustration, 0 (calm) to 1 (very frustrated).

number | null
compliance_failures
required

Compliance checks that failed in the window.

integer
last_30_days
required
object
conversations
required

Conversations received in the window.

integer
with_outcome
required

Conversations with an outcome (customer calls that were scored).

integer
resolution_rate
required

Share of conversations with an outcome that were resolved.

number | null
handed_to_person_rate
required

Share handed to a person (a transfer, or a person requested and provided).

number | null
requests_for_person_not_honored
required

Conversations where the caller asked for a person and didn’t get one.

integer
avg_frustration
required

Average caller frustration, 0 (calm) to 1 (very frustrated).

number | null
compliance_failures
required

Compliance checks that failed in the window.

integer

Examples

Exampledefault

An agent on Watch

{
  "agent_id": "front-desk",
  "name": "Front desk",
  "environment": "live",
  "health_status": "watch",
  "reason": "Resolution 81% vs 87% 30-day baseline (−6 pts) since version 3.2.0",
  "group": {
    "id": "brightsmile-dental",
    "name": "BrightSmile Dental"
  },
  "last_7_days": {
    "conversations": 212,
    "with_outcome": 180,
    "resolution_rate": 0.81,
    "handed_to_person_rate": 0.09,
    "requests_for_person_not_honored": 2,
    "avg_frustration": 0.22,
    "compliance_failures": 0
  },
  "last_30_days": {
    "conversations": 905,
    "with_outcome": 774,
    "resolution_rate": 0.87,
    "handed_to_person_rate": 0.08,
    "requests_for_person_not_honored": 5,
    "avg_frustration": 0.19,
    "compliance_failures": 1
  }
}

Headers

Section titled “Headers”
Midwater-Request-Id
string
Example 
req_8Jx2kQ4mT9

The request’s ID, also in error bodies as error.request_id. Quote it when contacting support.

401

Section titled “401”

Missing, malformed, unknown or revoked API key.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "authentication_error",
    "message": "Missing or invalid API key. Use Authorization: Bearer mw_test_… or mw_live_…"
  }
}

403

Section titled “403”

The key is valid but not allowed to do this.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "permission_denied",
    "message": "This key can't do that",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

404

Section titled “404”

Not found in the key’s environment.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "not_found",
    "message": "Conversation not found"
  }
}

405

Section titled “405”

The path exists but doesn’t support this method. Allow lists the methods it does support.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "method_not_allowed",
    "message": "GET isn't supported here; use POST",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Allow
string
Example 
POST

The methods the path supports, e.g. POST.

429

Section titled “429”

Too many requests. Wait Retry-After seconds. The limits are published when they’re set.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

RateLimit-Limit
integer

Requests allowed in the current window. The numbers are published when the limits are set.

RateLimit-Remaining
integer

Requests left in the current window.

RateLimit-Reset
integer

Seconds until the window resets.

500

Section titled “500”

Something went wrong on Midwater’s side. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "server_error",
    "message": "Something went wrong on our side"
  }
}

503

Section titled “503”

Midwater is briefly unavailable. Retry with backoff, honouring Retry-After when present.

Media typeapplication/json
object
error
required
object
type
required

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.

string
Allowed values: invalid_json authentication_error permission_denied not_found method_not_allowed idempotency_conflict payload_too_large validation_error rate_limited server_error service_unavailable
message
required

Human-readable; may change.

string
fields

Validation errors by dotted path, e.g. transcript.0.speaker. _root for the body as a whole.

object
key
additional properties
Array<string>
request_id

The request’s ID, the same as the Midwater-Request-Id header.

string

Example 

{
  "error": {
    "type": "service_unavailable",
    "message": "Midwater is briefly unavailable",
    "request_id": "req_8Jx2kQ4mT9"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.