# Schedule report subscriptions

Instead of checking the [uptime report](/reports/uptime-reports/) yourself, you can have HostTracker generate
and deliver it automatically on a schedule, to a contact you choose.

## What a report contains

A report covers one monitor's activity since the last one was sent (or the range you request for an
on-demand report): its up/down state over the period, uptime and response-time statistics, the outages that
occurred, the incident records behind them, and - if you choose - the detailed check log. Which of these
appear is controlled by the sections you pick (see below); a periodic subscription always includes state,
stats, outages and incidents, and you choose the output format.

## Settings reference

| Setting (UI label) | API field | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| Contact | `contactId` (path segment) | one of your alert contacts | - | - | Who receives the report. Must be an Email contact - reports are Email-only. |
| Frequency | `frequencies` | set of `daily`, `weekly`, `monthly`, `quarterly`, `yearly` | none | which frequencies are available depends on your plan | How often the report is generated and sent for this monitor/contact pair. You can subscribe a pair to more than one frequency at once. |
| Format | (report-generation only; a scheduled subscription uses the account's report-format setting) | `pdf`, `html`, `xml`, `csv` | `pdf` | - | The file/rendering the report is delivered as. |

## Subscribe a contact to a report in the app

1. Open a monitor's settings and go to its **Reports** section (alongside its alert **Subscriptions**).
2. Choose the **contact** to deliver the report to (add them as a contact first if they aren't one yet).
3. Choose how often it's sent - **daily**, **weekly**, **monthly**, **quarterly** or **yearly**. You can pick
   more than one.
4. Choose the delivery **format**.
5. **Save**.

The contact then receives a report on that schedule, covering that monitor's uptime and check activity for
the period since the last one.

## Formats

Reports can be delivered as:

- **PDF** - a formatted document, the most common choice for sharing with a client or manager.
- **HTML** - viewable directly in an email client or browser.
- **XML** - for feeding into another system.
- **CSV** - the raw data, for spreadsheets.

## Who can receive a report

A report is delivered to a **contact** - the same contacts you use for alerts, and it must be an **Email**
contact (reports are not sent by SMS, voice or messenger channels). If you want a report emailed to someone
who isn't already a contact on your account, add them as one first.

## Do it with the API or MCP

**Managing the schedule:** `PUT /monitor/{monitorId}/report/{contactId}` sets the whole frequency set for
that monitor/contact pair in one call (idempotent - send every frequency you want the pair to have, not just
the one you're adding); `GET /monitor/{monitorId}/report` lists who a monitor reports to and on what
schedule; `DELETE /monitor/{monitorId}/report/{contactId}` removes one pair.

```
PUT /monitor/<monitorId>/report/<contactId>
{ "frequencies": ["weekly", "monthly"] }
```

**Generating a report on demand** (for a one-off document, or to build your own summary) is asynchronous:

```
POST /monitor/report
{
  "monitorIds": ["<id1>", "<id2>"],
  "from": 1758000000,
  "to": 1758604800,
  "format": "pdf",
  "sections": ["state", "stats", "outages", "incidents"]
}
```

This answers a job id - poll `GET /job/{id}` until it concludes, then read the finished job's report content
url. An MCP client uses the `generate_report` tool with the same fields (times in Unix seconds), then
`get_job`/`wait_for_job` to retrieve it; `list_report_types` lists the available formats, sections and
frequencies. For a quick numeric summary instead of a rendered document, `get_uptime_summary` and
`list_incidents` (see [the uptime report page](/reports/uptime-reports/)) are usually the faster path - reach
for `generate_report` when you actually need the formatted file.

## Limits and gotchas

- A report contact must be **Email** type - subscribing a non-Email contact to a report is refused.
- Which frequencies are available depends on your plan; a plan with no reporting entitlement refuses every
  frequency.
- `PUT .../report/{contactId}` **replaces** the frequency set for that pair - send the full set you want, not
  a delta.

## Related

- [The account-wide uptime report](/reports/uptime-reports/)
- [What is an incident](/incidents/what-is-an-incident/)