--- title: "Team On-Call and Statistics" description: "Read who is on call for a team right now, the team's on-call calendar for a time window, and the team's incident statistics." --- Read-only views of one team: the current on-call set per tier, the on-call calendar, and incident statistics. For the organization-wide on-call view see [Who Is On Call](/api/incident-management/on-call). ## Authentication Base IM access: an IM-eligible role (`admin`, `editor` or `responder`) or an organization-wide API token, and Incident Management activated for the organization. No team role is needed. A team of another organization answers `404`. ## On-call now `GET /api/im/teams/:id/on-call-now` One entry per escalation tier, in tier order, with everyone on call in that tier right now. Overrides are already applied. A tier with nobody on call (no schedule, or a gap) has an empty `users` array. ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/on-call-now" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json [ { "tierId": 21, "tierOrder": 1, "users": [{ "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null }] }, { "tierId": 22, "tierOrder": 2, "users": [] } ] ``` ## Calendar `GET /api/im/teams/:id/calendar` On-call spans of all tiers in a time window, as a flat list ordered by start. Team-level overrides are already applied. ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from` | string | Yes | ISO 8601 timestamp, window start (inclusive). | | `to` | string | Yes | ISO 8601 timestamp, window end (exclusive). Must be after `from`. | | `tier` | integer | No | A tier id of this team: only that tier's spans. An id that is not one of the team's tiers returns `[]`. | ### Example (cURL) ```bash curl -X GET "$BASE_URL/api/im/teams/3/calendar?from=2026-10-01T00:00:00Z&to=2026-11-01T00:00:00Z" \ -H "Authorization: Bearer $TOKEN" ``` ### Response `200 OK` ```json [ { "scheduleId": 7, "tierOrder": 1, "userId": "u_abc123", "userName": "Ada Lovelace", "startsAt": "2026-09-28T07:00:00.000Z", "endsAt": "2026-10-05T07:00:00.000Z", "userImage": null }, { "scheduleId": null, "tierOrder": 1, "userId": "u_def456", "userName": "Bob Fixit", "startsAt": "2026-10-10T18:00:00.000Z", "endsAt": "2026-10-12T08:00:00.000Z", "userImage": null, "isTeamOverride": true } ] ``` - A span overlaps the window but may start before `from` or end after `to`. - `scheduleId: null` with `isTeamOverride: true` marks a span that comes from a team-level override rather than a schedule. The key is absent on all other spans. - A team without tiers returns `[]`. ## Incident statistics `GET /api/im/teams/:id/incidents/stats` Counts and response times of the team's incidents triggered in a window, the same numbers for the equally long window right before it, and one data point per day. Test incidents are not counted. ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `from` | string | Yes | ISO 8601 timestamp, window start (inclusive). | | `to` | string | Yes | ISO 8601 timestamp, window end (exclusive). At most 400 days after `from`. | | `tz` | string | No | IANA zone for the daily buckets. Missing or invalid falls back to the team's timezone, then `UTC`. | | `severity` | string | No | Only these severities: `sev1` to `sev4`. Repeatable (`?severity=sev1&severity=sev2`). | | `status` | string | No | Only these statuses: `triggered`, `acknowledged`, `investigating`, `identified`, `monitoring`, `resolved`, `merged`. Repeatable. | ### Example (cURL) ```bash curl -G "$BASE_URL/api/im/teams/3/incidents/stats" \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "from=2026-10-01T00:00:00+02:00" \ --data-urlencode "to=2026-10-08T00:00:00+02:00" \ --data-urlencode "tz=Europe/Berlin" ``` ### Response `200 OK` ```json { "from": "2026-09-30T22:00:00.000Z", "to": "2026-10-07T22:00:00.000Z", "comparisonFrom": "2026-09-23T22:00:00.000Z", "comparisonTo": "2026-09-30T22:00:00.000Z", "current": { "total": 12, "resolved": 10, "resolvedPct": 83.3, "open": 2, "mttaSeconds": 184, "ttaMedianSeconds": 95, "mttrSeconds": 2710, "ttrMedianSeconds": 1800 }, "previous": { "total": 8, "resolved": 8, "resolvedPct": 100, "open": 0, "mttaSeconds": 240, "ttaMedianSeconds": 150, "mttrSeconds": 3300, "ttrMedianSeconds": 2400 }, "timeSeries": [ { "date": "2026-10-01", "count": 3, "resolvedCount": 3, "mttaSeconds": 120, "mttrSeconds": 1500 }, { "date": "2026-10-02", "count": 0, "resolvedCount": 0, "mttaSeconds": null, "mttrSeconds": null } ] } ``` - `open` counts incidents in `triggered`, `acknowledged`, `investigating`, `identified` or `monitoring`. `merged` incidents are in `total` but in neither `resolved` nor `open`. - `resolvedPct` is `null` when `total` is `0`. MTTA/MTTR values are seconds, means and medians over the incidents that were acknowledged or resolved; `null` when there are none. - `timeSeries` has one point per calendar day of the window in `tz`, including days without incidents. ## Common errors - `401 Unauthorized` (`unauthorized`) when not authenticated - `403 Forbidden` (`imAccessDenied`) for a customer-scoped token, or a session without an IM-eligible role - `403 Forbidden` (`imNotEnabled`) when Incident Management is not activated for the organization - `404 Not Found` (`imTeamNotFound`) when the team does not exist or belongs to another organization - `400 Bad Request` (`invalidRequestBody`) when `:id` is not a positive integer, or (statistics) a `severity` or `status` value is unknown - `422 Unprocessable Entity` (`invalidRequestBody`) (calendar) when `from` or `to` is missing or not a valid timestamp, `from` is not before `to`, or `tier` is not a positive integer - `400 Bad Request` (`imReportRangeRequired`) (statistics) when `from` or `to` is missing or not a valid timestamp - `400 Bad Request` (`imReportRangeInvalid`) (statistics) when `from` is not before `to` - `400 Bad Request` (`imReportRangeTooLarge`) (statistics) when the window is longer than 400 days