Group monthly summary

The monthly summary returns one group's month in a single request: totals for the group and one entry for each site in it. It is the same data as the monthly summary email, limited to the sites in the group, so the figures match what you send a client. Use it to build a client report from your own code. Any key can call it, a read key included.

Request

Find the group's id with the list groups operation in the API reference. A group that isn't in your workspace answers 404.

export GROUP_ID="the group's id"
curl -fsS -H "X-API-Key: $OCTOPING_API_KEY" "https://octoping.com/api/groups/$GROUP_ID/monthly-summary?month=2026-10"

To print one line for each site, pipe the answer to jq.

curl -fsS -H "X-API-Key: $OCTOPING_API_KEY" "https://octoping.com/api/groups/$GROUP_ID/monthly-summary?month=2026-10" \
  | jq -r '.sites[] | [.url, .uptime_percentage, .outage_count] | @tsv'

Response

The answer is JSON with these keys. A trimmed example follows the tables.

totals

Each entry in sites

Each outage

{
  "group": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Acme Corp"
  },
  "month": "2026-10",
  "period": {
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-11-01T00:00:00Z"
  },
  "generated_at": "2026-11-02T08:15:00Z",
  "totals": {
    "sites": 2,
    "uptime_percentage": 99.84,
    "outages": 1,
    "downtime_seconds": 2760,
    "average_response_time_ms": 412.5,
    "content_changes": 3,
    "dns_changes": 0,
    "hosting_changes": 0,
    "data_truncated": false
  },
  "sites": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "https://acme.example",
      "url": "https://acme.example",
      "uptime_percentage": 99.68,
      "average_response_time_ms": 388.2,
      "outage_count": 1,
      "downtime_seconds": 2760,
      "outages": [
        {
          "started_at": "2026-10-14T02:10:00Z",
          "ended_at": "2026-10-14T02:56:00Z",
          "duration_seconds": 2760,
          "reason": {
            "code": "http_server",
            "label": "Service Unavailable (HTTP 503)"
          }
        }
      ],
      "ssl": {
        "expires_at": "2027-01-09T23:59:59Z",
        "days_left": 68,
        "issuer": "Let's Encrypt"
      },
      "domain": {
        "expires_at": "2027-06-30T00:00:00Z",
        "days_left": 240,
        "registrar": "Example Registrar"
      },
      "dns_change_count": 0,
      "dns_changes": [],
      "hosting_change_count": 0,
      "hosting_changes": [],
      "content_change_count": 3,
      "content_changes": [
        {
          "detected_at": "2026-10-22T09:30:00Z"
        },
        {
          "detected_at": "2026-10-12T14:05:00Z"
        },
        {
          "detected_at": "2026-10-03T08:00:00Z"
        }
      ],
      "data_truncated": false
    }
  ]
}

Null means no data

A site with nothing recorded in the month reports null for uptime_percentage, average_response_time_ms, outage_count and downtime_seconds. Zero outages means the site was checked and stayed up. Null means the month holds nothing to report. In the same way, totals.outages and totals.downtime_seconds are null when no site has anything recorded, so an empty month never reads as a clean one.

Lists are capped

Each list in a site's entry holds the newest 50 entries, newest first, and the true number sits beside it in outage_count, dns_change_count, hosting_change_count and content_change_count. A list that is shorter than its count is a cut list, and the count is the number to report.

Certificate and domain expiry

The certificate and domain expiry are the latest known values and are not limited to the month the summary covers. days_left is counted from generated_at to expires_at in whole days, and it is negative once the certificate or registration has expired.

How current the answer is

OctoPing reuses an answer for 5 minutes, or 60 minutes once the month is over. A change to the group's sites, such as a site moved in or out or a site's URL, gets a fresh answer. A new group name shows at once, because the name isn't part of the reused figures. generated_at says when the figures were computed, so polling faster than that returns the same numbers and spends requests from the workspace's limits.

When another summary is being prepared

Computing a month of checks takes a moment, so OctoPing prepares one summary at a time for each workspace. A request that needs a fresh one while another is being prepared is refused with HTTP 429, the code summary_in_progress and a Retry-After header. Wait that many seconds and ask again. A request that finds an answer it can reuse is never refused for this reason. The refused request counts against the workspace's limits, so don't retry in a tight loop. The API keys page lists the codes that requests made with a key are refused with.