Incidents API

List, create, and delete incidents using a simple HTTP API.

Do you need help with the integration?

Let us know at hello@betteruptime.com.

Obtaining an API token

Please, see Obtaining an API token.

get
Listing all existing incidents

https://betteruptime.com/api/v2/incidents
List all incidents with an option to filter incidents by monitor.
Request
Response
Request
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Query Parameters
from
optional
string
Return only incidents from a certain date (format YYYY-MM-DD)
to
optional
string
Return incidents until a certain date (format YYYY-MM-DD)
monitor_id
optional
integer
Filter incidents belonging to a specified monitor
heartbeat_id
optional
integer
Filter incidents belonging to a specified heartbeat
Response
200: OK
Returns list of existing incidents
{
"data": [
{
"id": "25",
"type": "incident",
"attributes": {
"name": "betteruptime homepage",
"url": "https://betteruptime.com/",
"http_method": "get",
"cause": "Status 500",
"incident_group_id": null,
"started_at": "2020-03-09T17:37:56.662Z",
"acknowledged_at": null,
"acknowledged_by": null,
"resolved_at": null,
"resolved_by": null,
"response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
"response_options": "{}",
"regions": ["us", "eu", "as", "au"],
"response_url": null,
"screenshot_url": null,
"escalation_policy_id": null,
"call": true,
"sms": true,
"email": true,
"push": true
},
"relationships": {
"monitor": {
"data": {
"id": "2",
"type": "monitor"
}
}
}
},
{
"id": "23",
"type": "incident",
"attributes": {
"name": "disk usage monitoring",
"url": null,
"http_method": null,
"cause": "Disk space usage high",
"incident_group_id": null,
"started_at": "2020-03-04T13:30:45.583Z",
"acknowledged_at": "2020-03-04T13:32:14.121Z",
"acknowledged_by": "John Smith",
"resolved_at": "2020-03-04T14:21:17.137Z",
"resolved_by": "John Smith",
"response_content": null,
"response_options": null,
"regions": null,
"response_url": null,
"screenshot_url": null,
"escalation_policy_id": null,
"call": false,
"sms": false,
"email": true,
"push": true
},
"relationships": {
"webhook_integration": {
"data": {
"id": "30579",
"type": "webhook_integration"
}
}
}
}
],
"pagination": {
"first": "https://betteruptime.com/api/v2/incidents?page=1",
"last": "https://betteruptime.com/api/v2/incidents?page=4",
"prev": null,
"next": "https://betteruptime.com/api/v2/incidents?page=2"
}
}
Example cURL
Example cURL
curl --request GET \
--url "https://betteruptime.com/api/v2/incidents?from=2021-01-01&to=2021-01-31" \
--header 'authorization: Bearer YOUR_API_TOKEN'

get
Listing a single incident

https://betteruptime.com/api/v2/incident/:incident_id
Returns a single incident.
Request
Response
Request
Path Parameters
incident_id
required
string
The ID of the incident you want to get
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
Returns a single incident
{
"data": {
"id": "25",
"type": "incident",
"attributes": {
"name": "betteruptime homepage",
"url": "https://betteruptime.com/",
"http_method": "get",
"cause": "Status 500",
"incident_group_id": null,
"started_at": "2020-03-09T17:37:56.662Z",
"acknowledged_at": null,
"acknowledged_by": null,
"resolved_at": null,
"resolved_by": null,
"response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
"response_options": "{}",
"regions": ["us", "eu", "as", "au"],
"response_url": null,
"screenshot_url": null,
"escalation_policy_id": null,
"call": true,
"sms": true,
"email": true,
"push": true
},
"relationships": {
"monitor": {
"data": {
"id": "2",
"type": "monitor"
}
}
}
},
"included": {
"id": "2",
"type": "monitor",
"attributes": {
"url": "https://betteruptime.com/",
"pronounceable_name": "Better Uptime homepage",
"monitor_type": "status",
"monitor_group_id": null,
"required_keyword": null,
"verify_ssl": true,
"check_frequency": 30,
"call": false,
"sms": false,
"email": true,
"push": true,
"team_wait": 180,
"http_method": "get",
"request_timeout": 30,
"recovery_period": 180,
"request_body": "",
"paused_at": null,
"last_checked_at": "2020-12-11T08:15:34.000Z",
"created_at": "2020-02-28T19:30:09.956Z",
"updated_at": "2020-11-23T09:08:20.817Z"
}
}
}
Example cURL
Example cURL
curl --request GET \
--url https://betteruptime.com/api/v2/incidents/123456789 \
--header 'Authorization: Bearer YOUR_API_TOKEN'

get
List of incident timeline events

https://betteruptime.com/api/v2/incident/:incident_id/timeline
Returns a list of timeline items for the given incident.
Request
Response
Request
Path Parameters
incident_id
required
string
The ID of the incident you want to examine
Headers
Autnorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
Returns a list of timeline items. The structure of the data attribute of the timeline items depends on the item type. The item_type can have these values: - generic - generic_card - timeline_truncated - response_item - payload - comment
{
"data": [
{
"id": "2021-02-12 23:59:59 UTC",
"type": "timeline_item",
"attributes": {
"item_type": "timeline_truncated",
"at": "2021-02-12T23:59:59.000Z",
"data": {
"title": "Skipping 123 timeline events"
}
}
},
{
"id": "23",
"type": "timeline_item",
"attributes": {
"item_type": "comment",
"at": "2021-02-12T10:44:46.618Z",
"data": {
"title": null,
"content": {
"text": "Some comment with attachment",
"user": {
"id": 123,
"name": "John Smith"
}
},
"attachments": [
{
"size": 44369,
"filename": "Screenshot 2021-02-12 at 10.44.45.png",
"mime_type": "image/png",
"url": "https://some-storage.s3.amazonaws.com/attachments/abc123.png"
}
]
}
}
},
{
"id": "107107309",
"type": "timeline_item",
"attributes": {
"item_type": "generic_card",
"at": "2021-02-12T07:49:14.539Z",
"data": {
"title": "Some title",
"content": "John Smith opened the incident email sent to john@smith.com.",
"links": ["https://betteruptime.com/team/1/team-members/1"]
}
}
},
{
"id": "2470302-content-response",
"type": "timeline_item",
"attributes": {
"item_type": "response_item",
"at": "2021-02-12T06:42:25.905Z",
"data": {
"title": "Page response",
"content": "[\"Some response data\"]"
}
}
},
{
"id": "2107504",
"type": "timeline_item",
"attributes": {
"item_type": "payload",
"at": "2021-02-11T07:52:57.540Z",
"data": {
"title": "Datadog",
"content": "Datadog alert.",
"attachments": [
{
"size": 123456,
"filename": "File.png",
"mime_type": "image/png",
"url": "https://some-storage.s3.amazonaws.com/attachments/xyz123.png"
}
]
}
}
},
{
"id": "incident-started",
"type": "timeline_item",
"attributes": {
"item_type": "generic",
"at": "2021-02-10T04:02:57.755Z",
"data": {
"content": "Incident started.",
"links": []
}
}
}
]
}
Example cURL
Example cURL
curl --request GET \
--url https://betteruptime.com/api/v2/incidents/123456789/timeline \
--header 'Authorization: Bearer YOUR_API_TOKEN'

post
Creating a new incident

https://betteruptime.com/api/v2/incidents
This will create a new incident and alert the current on-call person.
Request
Response
Request
Headers
Content-Type
required
string
application/json
Authentication
required
string
Authentication token to track down who is emptying our stocks.
Form Data Parameters
requester_email
required
string
E-mail of the user who requested the incident
summary
required
string
Brief summary of the incident
description
optional
string
Full description of the incident
call
optional
boolean
Should we call the on-call person?
sms
optional
boolean
Should we send an SMS to the on-call person?
email
optional
boolean
Should we send an email to the on-call person?
push
optional
boolean
Should we send a push notification to the on-call person?
team_wait
optional
integer
How long to wait before escalating the incident alert to the team. Leave blank to disable escalating to the entire team.
Response
200: OK
Cake successfully retrieved.
{
"data": {
"id": "123456789",
"type": "incident",
"attributes": {
"name": "betteruptime homepage",
"url": "https://betteruptime.com/",
"http_method": "get",
"cause": "Status 500",
"incident_group_id": null,
"started_at": "2020-03-09T17:37:56.662Z",
"acknowledged_at": null,
"acknowledged_by": null,
"resolved_at": null,
"resolved_by": null,
"response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
"response_options": "{}",
"regions": ["us", "eu", "as", "au"],
"response_url": null,
"screenshot_url": null,
"escalation_policy_id": null,
"call": true,
"sms": true,
"email": true,
"push": true
},
"relationships": {
"monitor": {
"data": {
"id": "2",
"type": "monitor"
}
}
}
}
}
404: Not Found
Authentication failed
Example cURL
Example cURL
curl --request GET \
--url https://betteruptime.com/api/v2/incidents \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"summary": "Test incident", "requester_email": "my-great-email@example.com", "description": "No need to worry, everything is fine, this is just testing the great Better Uptime API."}'

delete
Deleting an existing incident

https://betteruptime.com/api/v2/incidents/:incident_id
Request
Response
Request
Path Parameters
incident_id
required
string
The ID of the incident you want to delete
Headers
Authorization
required
string
Bearer YOUR_API_TOKEN
Response
200: OK
Returns an empty response
Example cURL
Example cURL
curl --request DELETE \
--url https://betteruptime.com/api/v2/incidents/123456 \
--header 'Authorization: Bearer YOUR_API_TOKEN'