A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Better Stack API is how an app or AI agent works with a Better Stack team: listing monitors, creating an incident that pages the on-call person, acknowledging or resolving an active incident, or managing heartbeats and status pages. Access is granted through a team-scoped API token sent as a bearer token, and that token can reach every resource the team owns because Better Stack does not split it into per-endpoint permissions. The API can push events to a configured URL when an incident or monitor changes, so an integration learns about activity without polling.
How an app or AI agent connects to Better Stack determines what it can reach. There is a route for making calls with an API token, a route for receiving events when something changes, and a hosted server that exposes Better Stack tools to agents, and each is governed by the token behind it.
The Uptime API is a JSON:API-style REST API at https://uptime.betterstack.com, with resources under api/v2 (monitors, heartbeats, on-call, status pages) and api/v3 (incidents, escalation policies, metadata). A call authenticates with a team-scoped bearer token, and a list response carries a pagination object with first, last, prev, and next URLs.
A hosted Model Context Protocol server at https://mcp.betterstack.com exposes Better Stack tools to AI assistants. It authenticates with OAuth, which prompts a browser sign-in, or with an API token for clients without OAuth support. Uptime tools cover listing monitors and heartbeats, getting monitor details and availability, and creating, acknowledging, escalating, and resolving incidents, plus on-call schedules, escalation policies, and status pages. Telemetry and error-tracking tools cover querying logs and traces, building dashboards, and analyzing exceptions.
Better Stack POSTs to a URL configured under Uptime, Integrations, Exporting data, when an incident or monitor changes. Incident events fire on created, acknowledged, resolved, reopened, and commented; monitor events fire on created, updated, paused, unpaused, and deleted; an on-call event fires when the on-call contact changes. A comment event includes a top-level comment field with content and author.
A team-scoped token created in the Better Stack dashboard, sent as a bearer token in the Authorization header. It manages one team's Uptime resources and has no granular per-endpoint scopes, so it can read and write every Uptime resource the team owns. A global token can target a specific team by passing team_name on list endpoints.
The hosted MCP server supports OAuth, which prompts a browser sign-in so an MCP client connects without configuring a token. Clients that do not support OAuth pass an API token in the Authorization header instead.
The Better Stack Uptime API is split into areas an agent can act on, like monitors, heartbeats, incidents, on-call schedules, escalation policies, and status pages. Each area has its own methods, and a write can create a real incident that pages a person or pause a monitor that watches a live service.
Methods for listing and managing uptime monitors and their availability.
Methods for organizing monitors into groups.
Methods for managing heartbeats that watch scheduled jobs and cron tasks.
Methods for listing, creating, and responding to incidents.
Methods for reading and managing on-call schedules.
Methods for reading and managing escalation policies.
Methods for managing public status pages.
Methods for reading and writing custom key-value metadata on resources.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MonitorsMethods for listing and managing uptime monitors and their availability.6 | ||||||
| GET | /api/v2/monitors | List all monitors, with optional filters by url, pronounceable_name, and team_name. | read | — | Current | |
The team-scoped token reads every monitor the team owns; Better Stack has no read-only or per-resource scope. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/monitors/{id} | Retrieve a single monitor's details. | read | — | Current | |
Read-only; reachable by any token for the team that owns the monitor. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/monitors | Create a monitor; requires a monitor_type and, for most types, a url. | write | — | Current | |
monitor_type accepts values like status, keyword, ping, tcp, dns, and playwright. A 422 returns an errors object keyed by field. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook event monitor.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/monitors/{id} | Update an existing monitor, including pausing or unpausing it. | write | — | Current | |
Pausing or unpausing a monitor is done through this update method. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook event monitor.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/monitors/{id} | Permanently delete a monitor. | write | — | Current | |
Irreversible; the monitor stops watching the service. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook event monitor.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/monitors/{id}/availability | Retrieve a monitor's availability summary over a time range. | read | — | Current | |
Read-only reporting data. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Monitor groupsMethods for organizing monitors into groups.2 | ||||||
| GET | /api/v2/monitor-groups | List all monitor groups. | read | — | Current | |
Read-only. Acts onmonitor_group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/monitor-groups | Create a monitor group. | write | — | Current | |
Groups monitors for organization on dashboards and status pages. Acts onmonitor_group Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
HeartbeatsMethods for managing heartbeats that watch scheduled jobs and cron tasks.5 | ||||||
| GET | /api/v2/heartbeats | List all heartbeats that watch scheduled jobs and cron tasks. | read | — | Current | |
Read-only. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/heartbeats/{id} | Retrieve a single heartbeat's details. | read | — | Current | |
Read-only. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/heartbeats | Create a heartbeat with an expected period, returning a URL to ping when a job runs. | write | — | Current | |
The job pings the returned heartbeat URL with HEAD, GET, or POST; a missed period opens an incident. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/heartbeats/{id} | Update an existing heartbeat's configuration. | write | — | Current | |
Changes the expected period or alerting on a heartbeat. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/heartbeats/{id} | Permanently delete a heartbeat. | write | — | Current | |
Irreversible; the job is no longer watched. Acts onheartbeat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IncidentsMethods for listing, creating, and responding to incidents.6 | ||||||
| GET | /api/v3/incidents | List incidents, with filters by monitor, date range, resolved and acknowledged state, and metadata. | read | — | Current | |
Read-only. Pages with a default of 10 and a maximum of 50 per page. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v3/incidents/{id} | Retrieve a single incident's details. | read | — | Current | |
Read-only. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/incidents | Create an incident, which alerts the on-call person. | write | — | Current | |
Returns 201 with notification flags for call, sms, email, and push; pages whoever the escalation policy names. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook event incident.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/incidents/{id}/acknowledge | Acknowledge an ongoing incident, signaling someone is responding. | write | — | Current | |
Stops further escalation for the incident. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook event incident.acknowledgedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/incidents/{id}/resolve | Resolve an active incident. | write | — | Current | |
Closes the incident; it can later be reopened. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook event incident.resolvedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v3/incidents/{id} | Permanently delete an incident. | write | — | Current | |
Irreversible; removes the incident record. Acts onincident Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
On-call schedulesMethods for reading and managing on-call schedules.2 | ||||||
| GET | /api/v2/on-calls | List on-call schedules, with optional team_name filtering for a global token. | read | — | Current | |
Read-only. Returns each schedule's name, default_calendar flag, and related on-call users. Acts onon_call_calendar Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/on-calls/{id} | Retrieve a single on-call schedule and who is currently on call. | read | — | Current | |
Read-only. Acts onon_call_calendar Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Escalation policiesMethods for reading and managing escalation policies.2 | ||||||
| GET | /api/v3/policies | List escalation policies, with an optional team_name filter. | read | — | Current | |
Read-only. A policy defines who is alerted, and in what order, until an incident is acknowledged. Acts onpolicy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/policies | Create an escalation policy. | write | — | Current | |
Defines the alerting steps and notification channels for incidents. Acts onpolicy Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Status pagesMethods for managing public status pages.3 | ||||||
| GET | /api/v2/status-pages | List all status pages. | read | — | Current | |
Read-only. Acts onstatus_page Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/status-pages | Create a public status page. | write | — | Current | |
A status page is publicly visible once published. Acts onstatus_page Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/status-pages/{id}/resources | Add a resource, like a monitor, to a status page. | write | — | Current | |
Controls what a public status page displays. Acts onstatus_page_resource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MetadataMethods for reading and writing custom key-value metadata on resources.2 | ||||||
| GET | /api/v3/metadata | List metadata for a given resource, filtered by owner_type and owner_id. | read | — | Current | |
owner_type accepts Monitor, Heartbeat, Incident, WebhookIntegration, EmailIntegration, IncomingWebhook, or CallRouting; omitting owner_id returns metadata for all resources. Acts onmetadata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v3/metadata | Create or update a metadata record on a resource. | write | — | Current | |
Writes a key-value pair against an owner_type and owner_id; values can be typed, such as a schedule reference. Acts onmetadata Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Better Stack can notify an app when something happens in a team, like an incident being created, acknowledged, or resolved, or a monitor being paused. It sends a POST request to a URL configured in the dashboard, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
Incident created | A POST is sent when a new incident is created, the point where the on-call person is paged. | /api/v3/incidents |
Incident acknowledged | A POST is sent when an ongoing incident is acknowledged, signaling someone is responding. | /api/v3/incidents/{id}/acknowledge |
Incident resolved | A POST is sent when an active incident is resolved. | /api/v3/incidents/{id}/resolve |
Monitor created | A POST is sent when a new monitor is created. | /api/v2/monitors |
Monitor updated, paused, or unpaused | A POST is sent when a monitor is updated, paused, or unpaused. | /api/v2/monitors/{id} |
Monitor deleted | A POST is sent when a monitor is deleted. | /api/v2/monitors/{id} |
Better Stack paginates its list endpoints with a page number and a page size, and does not publish a numeric request rate in its developer docs.
Better Stack does not publish a numeric request rate (requests per second or per minute) for the Uptime API in its developer documentation. The getting-started and reference pages describe authentication, pagination, and the JSON:API response shape, but state no per-token quota, no rate-limit response headers, and no documented 429 behavior. An integration should apply its own backoff and retry rather than rely on a stated ceiling.
List endpoints page with two query parameters: page sets the page number starting at 1, and per_page sets the page size, which defaults to 50 and may go up to 250. The response includes a pagination object with first, last, prev, and next URLs, where prev is null on the first page and next is null on the last. The incidents endpoint pages with a smaller default of 10 and a maximum of 50.
A list page returns up to per_page items, capped at 250 for most resources and 50 for incidents. A monitor requires a monitor_type and, for most types, a url. Heartbeat ping requests to the public heartbeat URL accept HEAD, GET, or POST.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid token was provided, or it is not authorized for this team's resources. | Send a valid team-scoped token in the Authorization header as Bearer $TOKEN, and confirm it belongs to the right team. |
| 404 | not_found | The requested resource does not exist or is not visible to this token, for example an id that belongs to another team. | Verify the resource id and confirm the token's team owns it. |
| 422 | validation_error | The request was rejected by validation. The body returns an errors object keyed by field, such as base, with an array of messages like 'URL is invalid.' | Read the messages under each key in the errors object, fix the parameters, and resend. |
Better Stack versions its Uptime API in the path. Monitors, heartbeats, on-call schedules, and status pages sit on v2, while incidents, escalation policies, and metadata sit on v3.
The newer endpoints sit on v3 in the path. Incidents moved to v3 with richer filtering, by resolved and acknowledged state and by metadata, and escalation policies and metadata are served under v3. The incidents endpoint pages with a default of 10 and a maximum of 50.
The core Uptime resources are served under v2 in the path: monitors and monitor groups, heartbeats and heartbeat groups, on-call schedules, and status pages and their resources. List endpoints follow the JSON:API shape with page and per_page pagination, defaulting to 50 and up to 250 per page.
Pin to the version segment in each path; v2 and v3 endpoints coexist.
Better Stack Uptime API docs ↗Bollard AI sits between a team's AI agents and Better Stack. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.