WFM coverage

Español: Cobertura WFM.

GET /v1/wfm/coverage returns a derived staffing view for one UTC calendar day. It does not persist a forecast: each request recomputes the result from the append-only streams. The endpoint accepts dd_ and ddu_ credentials; a widget credential (ddw_) is forbidden.

Request

date is required and must be a YYYY-MM-DD UTC date within 366 days of today. The response always contains 48 half-hour intervals (interval_minutes: 30). These rules and the authentication boundary are from the getWfmCoverage operation in the vendored openapi/dialer-v1.yaml.

You can optionally simulate a target for this response by sending both threshold_ms and target_percent. threshold_ms accepts 1 through 86,400,000 milliseconds; target_percent accepts 1 through 100. Sending only one is invalid. The simulated target is not persisted and the response sets simulated to true.

curl -sG "$API/v1/wfm/coverage" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "date=2026-10-12" \
  --data-urlencode "threshold_ms=20000" \
  --data-urlencode "target_percent=80"

The query parameters, bounds and 400/401/403/429 responses are defined by getWfmCoverage in the vendored spec.

What the forecast means

The forecast averages the same weekday from the previous four weeks that have already ended, in 30-minute UTC slots. It counts offered inbound attempts: an original call_attempts row with corrects_id unset and direction=inbound, unless a later correction marks it not_placed.

The average handle time combines conversation time and agent wrap_up. For seats that also place outbound calls, that wrap_up is an upper bound because the source interval is not attached to a particular call.

The response uses source: "history" only after reaching both sample floors: at least two reference days and at least 30 offered calls. Otherwise it uses source: "estimate", a flat six offered calls per interval with an AHT of 300 seconds. This is explicitly a placeholder, not a prediction.

Response shape

The top-level response contains date, interval_minutes, source, simulated, history, target and intervals. The exact required names and types come from the WfmCoverageResponse schema in the vendored spec.

Each interval contains:

• start and end, as date-time values;
• forecast.volume, forecast.aht_ms and forecast.aht_source (slot, pooled or estimate);
• staffing, with required_agents, service_level, occupancy and reachable, or an inert reason;
• scheduled_agents, the planned full-time equivalents;
• coverage.gap (planned minus required) and coverage.ratio, or null when the target is inert.

Required staffing uses Erlang C against the tenant service target. The calculation searches up to 5,000 agents. If the target cannot be reached before that cap—or the target is 100%—reachable is false and the required count is capped. When the tenant has no usable service target, target and every interval's staffing report an inert reason and coverage is null.

Planned staffing comes from R11 planned shifts: paused shifts are excluded and overlapping shifts for one agent count once. These meanings, the cap, the inert reasons and the interval fields are defined by WfmCoverageResponse, WfmCoverageInterval and WfmInert in the vendored spec; the forecast and Erlang C rules are also recorded in core ADR #241.