---
title: "Page someone"
method: POST
path: "/alerts/page"
tags: ["Alerts"]
---

# Page someone

`POST /alerts/page`

## Request

- Base URL: `https://api.spectate.net/v1`
- URL: `https://api.spectate.net/v1/alerts/page`
- Auth: HTTP bearer

With nothing to attach it to: creates an alert with source `manual`, open until someone
resolves it or its incident resolves. With an `incident_id` whose alert still fires, the page
goes on that alert instead. Texts and calls use the team's credits.

## Request body

- PageSomeone: A page with nothing to attach it to.
  - `target_type` 'member' | 'schedule' | 'path', required: Who to page by hand. | | |---| | `member` <br/> A team member. | | `schedule` <br/> Whoever is on call for a schedule. | | `path` <br/> An escalation path. |
  - `target_id` string, uuid, required: The member's, schedule's or path's ID
  - `title` string, required: What the page is about, up to 255 characters
  - `message` string, nullable: More detail for the person paged, up to 2000 characters
  - `severity` 'critical' | 'high' | 'medium' | 'low': How urgent an alert or incident is. Escalation paths can branch on it. | | |---| | `critical` <br/> Customers are affected right now. | | `high` <br/> Serious, needs attention soon. | | `medium` <br/> Should be looked at. | | `low` <br/> Informational. |
  - `incident_id` string, uuid, nullable: An incident to tie this to: the new alert resolves with it

## Response `201`

The alert the page is on.

- Alert: An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
  - `id` string, uuid, required: Alert ID
  - `title` string, required: What's wrong
  - `description` string, nullable, required: More about it, as the source described it
  - `status` 'firing' | 'resolved', required: Whether an alert's problem is ongoing. | | |---| | `firing` <br/> The problem is ongoing; it escalates until acknowledged. | | `resolved` <br/> The problem is over. |
  - `severity` 'critical' | 'high' | 'medium' | 'low', required: How urgent an alert or incident is. Escalation paths can branch on it. | | |---| | `critical` <br/> Customers are affected right now. | | `high` <br/> Serious, needs attention soon. | | `medium` <br/> Should be looked at. | | `low` <br/> Informational. |
  - `source_type` 'uptime' | 'certificate' | 'performance' | 'dns' | 'host_metric' | 'domain' | 'external' | 'status_page' | 'manual', required: What raised an alert. | | |---| | `uptime` <br/> A monitor went down. | | `certificate` <br/> A monitor's certificate is invalid or expires soon. | | `performance` <br/> A monitor got slow. | | `dns` <br/> The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up. | | `host_metric` <br/> A host's metric condition held, or it stopped sending data. | | `domain` <br/> A domain expires soon, expired or its registration changed. | | `external` <br/> An alert source (external tool) fired it. | | `status_page` <br/> Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`). | | `manual` <br/> Someone paged by hand, with nothing else to attach it to. |
  - `resource` AlertResource, required: The resource an alert is about.
    - `type` 'monitor' | 'host' | 'domain' | 'status_page' | 'alert_source', required: What kind of resource an alert is about.
    - `id` string, uuid, required: The resource's ID, for example a monitor ID
    - `name` string, nullable, required: Its name or label
  - `fired_at` string, date-time, required: When it fired
  - `acknowledged_at` string, date-time, nullable, required: When it was acknowledged, which stopped its escalation; `null` while unacknowledged
  - `acknowledged_by` string, nullable, required: Who acknowledged it: a member's name, an API token, or how (for example a phone call)
  - `recovering_since` string, date-time, nullable, required: When the monitor came back up. The alert stays `firing` for the team's recovery wait and resolves when the monitor stays up; `null` at any other time
  - `group_leader_id` string, uuid, nullable, required: The alert that escalates for this one, when they're grouped; `null` when it escalates by itself
  - `snoozed_until` string, date-time, nullable, required: Until when someone snoozed it; `null` when it isn't snoozed. It counts as acknowledged until then
  - `muted_at` string, date-time, nullable, required: When maintenance muted it, so it pages nobody until the window ends; `null` when it isn't muted
  - `resolved_at` string, date-time, nullable, required: When it resolved; `null` while firing
  - `resolved_by` string, nullable, required: Who resolved it by hand: a member's name or an API token. `null` while firing, and when it resolved on its own because the problem was over
  - `labels` object, nullable, required: Labels the source sent (Prometheus, Grafana); `null` when it sent none
  - `links` AlertLink[], required: Links the source sent along
    - `label` string, required: What it opens
    - `url` string, uri, required: Where it goes

## Other responses

- `401`: `UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.
- `403`: `FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.
- `404`: `RESOURCE_NOT_FOUND`: there is no such resource in this team.
- `422`: `VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.
- `429`: `RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.

---

[API](https://skmtc.dev/spectate/apis/spectate-api.md) - [All operations](https://skmtc.dev/spectate/apis/spectate-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spectate/apis/spectate-api/revisions/9b1a233997de?raw)