Monitors API Reference

This guide provides detailed information about the Monitors API endpoints.

Authentication

All monitor endpoints require authentication using a Project API Token. Include your token in the Authorization header:

bash

Authorization: Bearer YOUR_PROJECT_API_TOKEN

For more information about authentication, see the Authentication Guide.

List Monitors

Retrieve a list of all monitors.

http

GET /api/v1/network_monitors
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET "https://app.uptinio.com/api/v1/network_monitors?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Example with search:

bash

curl -X GET "https://app.uptinio.com/api/v1/network_monitors?search=example" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter	Type	Description	Default
page	integer	Page number	1
per_page	integer	Items per page (max: 100)	25
sort	string	Sort order: `status` (monitors with incidents first, then successful, then paused) or `created_at`	`status`
search	string	Search query to filter monitors by name or URL (case-insensitive partial match)	-

Response

json

{
  "data": [
    {
      "id": 1,
      "uuid": "NM123",
      "name": "Website Uptime",
      "url": "https://example.com",
      "check_type": "http",
      "status": "success",
      "uptime": 99.95,
      "response_time": 125.5,
      "last_check": "2024-01-02T12:30:00Z",
      "open_incident_uuids": ["INC123", "INC456"],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 3,
    "total_count": 67,
    "sort": "status"
  }
}

Response Fields

Field	Type	Description
data	array	Array of network monitor objects
data[].id	integer	Monitor ID
data[].uuid	string	Monitor UUID
data[].name	string	Monitor name
data[].url	string	Monitor URL
data[].check_type	string	Type of check (http, tcp, ping, keyword, heartbeat)
data[].status	string	Current status (success, failure, paused, initializing)
data[].uptime	float	Uptime percentage for last 24 hours (0-100)
data[].response_time	float	Last response time in milliseconds
data[].last_check	string	ISO 8601 timestamp of last check
data[].open_incident_uuids	array	Array of UUIDs for ongoing (open) incidents
data[].created_at	string	ISO 8601 timestamp of creation
meta	object	Pagination metadata
meta.current_page	integer	Current page number
meta.per_page	integer	Number of items per page
meta.total_pages	integer	Total number of pages
meta.total_count	integer	Total number of items
meta.sort	string	Current sort order (`status` or `created_at`)
meta.search	string\|null	Search query used (if any)

Sorting

By default, monitors are sorted by status priority:

Monitors with ongoing incidents (failure status) - highest priority
Successful monitors (not paused, has transactions) - second priority
Paused monitors - lowest priority

Within each priority group, monitors are sorted by created_at in descending order (newest first).

To sort by creation date only, use sort=created_at.

Search

You can search for monitors by name or URL using the search parameter. The search is case-insensitive and performs a partial match (LIKE query).

Examples:

Search for monitors with "api" in name or URL: ?search=api
Search for monitors with "example.com" in URL: ?search=example.com
Combine search with pagination: ?search=test&page=1&per_page=10

The search will match monitors where either the name or url field contains the search term.

Create Monitor

Create a new monitor. The required and optional parameters vary depending on the monitor type.

http

POST /api/v1/network_monitors
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Common Parameters

These parameters apply to all monitor types:

Parameter	Type	Required	Description	Default
`check_type`	string	Yes	Type of monitor: `http`, `tcp`, `ping`, `keyword`, or `heartbeat`	-
`name`	string	No*	Descriptive name for the monitor	-
`minutes_interval`	integer	Yes	How often to check (in minutes). Must be > 0	-
`request_timeout`	integer	No	Maximum time to wait for response (1-60 seconds)	30
`check_ssl_errors`	boolean	No	Whether to check for SSL certificate errors	true
`domain_expiry_reminders`	boolean	No	Whether to send domain expiry reminders	true
`integration_uuids`	array	No	Array of integration UUIDs to notify	[]

* name is required for heartbeat monitors, optional for others.

Monitor Types

HTTP Monitor

Monitors websites and APIs by making HTTP requests. Verifies response codes, latency, SSL certificates, and domain expiration.

Required Parameters:

check_type: "http"
url: Target URL (e.g., "https://example.com")
http_method: HTTP method ("method_get", "method_post", "method_put", "method_patch", "method_delete", "method_head")
minutes_interval: Check interval in minutes

Optional Parameters:

name: Monitor name
request_timeout: Timeout in seconds (1-60, default: 30)
check_ssl_errors: Check SSL errors (default: true)
domain_expiry_reminders: Send domain expiry reminders (default: true)
follow_redirections: Follow HTTP redirects (default: true)
up_http_status_codes: Array of acceptable status codes (default: ["2xx", "3xx"])
auth_type: Authentication type ("none", "basic", "bearer", default: "none")
auth_username: Username for basic/bearer auth
auth_password: Password/token for basic/bearer auth
request_body: Request body for POST/PUT/PATCH requests
send_as_json: Send request body as JSON (default: false)
integration_uuids: Array of integration UUIDs

Example:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "My Website",
      "url": "https://example.com",
      "check_type": "http",
      "http_method": "method_get",
      "minutes_interval": 5,
      "check_ssl_errors": true,
      "follow_redirections": true,
      "up_http_status_codes": ["2xx", "3xx"]
    }
  }'

Example with Basic Authentication:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "Protected API",
      "url": "https://api.example.com/status",
      "check_type": "http",
      "http_method": "method_get",
      "minutes_interval": 5,
      "auth_type": "basic",
      "auth_username": "user",
      "auth_password": "pass"
    }
  }'

Example with POST Request:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "API Endpoint",
      "url": "https://api.example.com/webhook",
      "check_type": "http",
      "http_method": "method_post",
      "minutes_interval": 10,
      "request_body": "{\"test\": true}",
      "send_as_json": true
    }
  }'

TCP Port Monitor

Checks if a specific network port is open and accessible. Useful for monitoring databases, mail servers, or custom applications.

Required Parameters:

check_type: "tcp"
url: Hostname or IP address (e.g., "example.com" or "192.168.1.1")
port: Port number (1-65535)
minutes_interval: Check interval in minutes

Optional Parameters:

name: Monitor name
request_timeout: Timeout in seconds (1-60, default: 30)
integration_uuids: Array of integration UUIDs

Example:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "Database Server",
      "url": "db.example.com",
      "check_type": "tcp",
      "port": 5432,
      "minutes_interval": 5,
      "request_timeout": 10
    }
  }'

PING Monitor

Uses ICMP ping to verify if a server is online and responding. Measures basic connectivity and latency.

Required Parameters:

check_type: "ping"
url: Hostname or IP address (e.g., "example.com" or "8.8.8.8")
minutes_interval: Check interval in minutes

Optional Parameters:

name: Monitor name
request_timeout: Timeout in seconds (1-60, default: 30)
integration_uuids: Array of integration UUIDs

Example:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "Server Ping",
      "url": "192.168.1.1",
      "check_type": "ping",
      "minutes_interval": 5
    }
  }'

Keyword Monitor

Verifies webpage content by checking for specific keywords or phrases. An incident is created if the monitored keywords are missing from the webpage response.

Required Parameters:

check_type: "keyword"
url: Target URL (e.g., "https://example.com")
keywords: Comma-separated list of keywords or array of keywords (e.g., "keyword1,keyword2" or ["keyword1", "keyword2"])
minutes_interval: Check interval in minutes

Optional Parameters:

name: Monitor name
http_method: HTTP method ("method_get", "method_post", etc., default: "method_get")
request_timeout: Timeout in seconds (1-60, default: 30)
check_ssl_errors: Check SSL errors (default: true)
follow_redirections: Follow HTTP redirects (default: true)
auth_type: Authentication type ("none", "basic", "bearer", default: "none")
auth_username: Username for basic/bearer auth
auth_password: Password/token for basic/bearer auth
integration_uuids: Array of integration UUIDs

Example:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "Content Check",
      "url": "https://example.com",
      "check_type": "keyword",
      "keywords": "Welcome,Online",
      "http_method": "method_get",
      "minutes_interval": 10
    }
  }'

Heartbeat Monitor

A passive monitoring type where your system actively reports its status. Ideal for monitoring background jobs, cron tasks, or batch processes. No URL is required.

Required Parameters:

check_type: "heartbeat"
name: Monitor name (required for heartbeat monitors)
minutes_interval: Expected heartbeat interval in minutes

Optional Parameters:

request_timeout: Timeout in seconds (1-60, default: 30)
integration_uuids: Array of integration UUIDs

Example:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network_monitor": {
      "name": "Daily Backup Job",
      "check_type": "heartbeat",
      "minutes_interval": 1440
    }
  }'

Response

All monitor creation requests return the created monitor object:

json

{
  "id": 123,
  "uuid": "NMABC123",
  "name": "My Website",
  "url": "https://example.com",
  "check_type": "http",
  "status": "initializing",
  "paused": false,
  "minutes_interval": 5,
  "check_ssl_errors": true,
  "domain_expiry_reminders": true,
  "request_timeout": 30,
  "auth_type": "none",
  "http_method": "method_get",
  "request_body": null,
  "send_as_json": false,
  "follow_redirections": true,
  "port": null,
  "keywords": [],
  "integration_uuids": [],
  "up_http_status_codes": ["2xx", "3xx"],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Error Response

If validation fails, a 422 Unprocessable Entity response is returned:

json

{
  "errors": [
    "Url can't be blank",
    "Http method can't be blank"
  ]
}

Get Monitor

Retrieve details of a specific monitor.

http

GET /api/v1/network_monitors/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "id": 1,
  "uuid": "NM123",
  "name": "Website Uptime",
  "url": "https://example.com",
  "check_type": "http",
  "status": "success",
  "uptime": 99.95,
  "response_time": 125.5,
  "last_check": "2024-01-02T12:30:00Z",
  "open_incident_uuids": ["INC123", "INC456"],
  "created_at": "2024-01-01T00:00:00Z"
}

Update Monitor

Update an existing monitor.

http

PUT /api/v1/network_monitors/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X PUT https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "minutes_interval": 10
  }'

Request Body

json

{
  "name": "Updated Monitor Name",
  "interval": 120,
  "regions": ["us-east", "eu-west", "ap-south"]
}

Response

json

{
  "data": {
    "id": "mon_123",
    "name": "Updated Monitor Name",
    "type": "http",
    "status": "active",
    "url": "https://example.com",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Delete Monitor

Delete a monitor.

http

DELETE /api/v1/network_monitors/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X DELETE https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Pause Monitor

Pause a monitor so it stops running checks.

http

POST /api/v1/network_monitors/:uuid/pause
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/pause \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

Returns the monitor with paused: true.

json

{
  "id": 1,
  "uuid": "NM123",
  "paused": true
}

Resume Monitor

Resume a paused monitor so it starts running checks again.

http

POST /api/v1/network_monitors/:uuid/resume
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/resume \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

Returns the monitor with paused: false.

json

{
  "id": 1,
  "uuid": "NM123",
  "paused": false
}

Get Latest Transactions

Retrieve a paginated list of the latest transactions for a monitor.

http

GET /api/v1/network_monitors/:uuid/transactions
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/transactions?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter	Type	Description	Default
page	integer	Page number	1
per_page	integer	Items per page (max: 100)	50
status	string	Filter by status (success, failure)	all
transaction_type	string	Filter by type (http, tcp, ping, keyword, heartbeat)	all

Note:

Transactions are ordered by creation date in descending order (most recent first).
By default, only transactions from the last 1 hour are returned.
SSL and domain transactions are excluded from results and counts.

Response

json

{
  "data": [
    {
      "id": 123,
      "transaction_type": "http",
      "status": "success",
      "status_code": 200,
      "status_message": "OK",
      "response_time": 123.45,
      "queue_name": "us-east-1",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total_pages": 2,
    "total_count": 45
  }
}

Response Fields

Field	Type	Description
data	array	Array of transaction objects
data[].id	integer	Transaction ID
data[].transaction_type	string	Type of transaction (http, tcp, ping, keyword, heartbeat). Note: SSL and domain transactions are excluded.
data[].status	string	Transaction status (success, failure)
data[].status_code	integer\|null	HTTP status code (if applicable)
data[].status_message	string\|null	Status message
data[].response_time	float\|null	Response time in milliseconds
data[].queue_name	string\|null	Queue/location name where the check was performed
data[].created_at	string	ISO 8601 timestamp of creation
data[].updated_at	string	ISO 8601 timestamp of last update
meta	object	Pagination metadata
meta.current_page	integer	Current page number
meta.per_page	integer	Number of items per page
meta.total_pages	integer	Total number of pages
meta.total_count	integer	Total number of items

Get Monitor Data

Retrieve transaction data for a monitor with time range filtering.

http

GET /api/v1/network_monitors/:uuid/data
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/data?start_date=2024-01-01T00:00:00Z&end_date=2024-01-02T00:00:00Z&period_length=5" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter	Type	Description	Default
start_date	string	ISO 8601 date/time for start of range (e.g., `2024-01-01T00:00:00Z`)	24 hours ago
end_date	string	ISO 8601 date/time for end of range (e.g., `2024-01-02T00:00:00Z`)	now
period_length	integer	Period length in minutes (5, 15, 60, 360, 1440)	5

Note: start_date must be before end_date. Dates should be in ISO 8601 format (e.g., 2024-01-01T00:00:00Z or 2024-01-01T00:00:00+00:00).

Response

json

{
  "monitor_uuid": "MONITOR_UUID",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-02T00:00:00Z",
  "period_length_minutes": 5,
  "data": [
    {
      "period_start": "2024-01-01T00:00:00Z",
      "total_transactions": 12,
      "successful_transactions": 12,
      "success_rate": 100.0,
      "response_time_avg": 125.5,
      "transaction_type": 1
    },
    {
      "period_start": "2024-01-01T00:05:00Z",
      "total_transactions": 12,
      "successful_transactions": 11,
      "success_rate": 91.67,
      "response_time_avg": 130.2,
      "transaction_type": 1
    }
  ]
}

Response Fields

Field	Type	Description
monitor_uuid	string	UUID of the monitor
start_time	string	ISO 8601 timestamp of the start of the data range
end_time	string	ISO 8601 timestamp of the end of the data range
period_length_minutes	integer	Length of each period in minutes
data	array	Array of transaction data points
data[].period_start	string	ISO 8601 timestamp of the period start
data[].total_transactions	integer	Total number of transactions in the period
data[].successful_transactions	integer	Number of successful transactions
data[].success_rate	float	Success rate percentage (0-100)
data[].response_time_avg	float	Average response time in milliseconds
data[].transaction_type	integer	Type of transaction

Example Use Cases

Get last 24 hours with 5-minute intervals:

bash

# Using ISO 8601 dates
curl "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/data?start_date=2024-01-01T00:00:00Z&end_date=2024-01-02T00:00:00Z&period_length=5"

Get last 7 days with 1-hour intervals:

bash

curl "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/data?start_date=2024-01-01T00:00:00Z&end_date=2024-01-08T00:00:00Z&period_length=60"

Get last 30 days with 1-day intervals:

bash

curl "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/data?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T00:00:00Z&period_length=1440"

Get data for a specific date range:

bash

curl "https://app.uptinio.com/api/v1/network_monitors/MONITOR_UUID/data?start_date=2024-01-15T08:00:00Z&end_date=2024-01-15T18:00:00Z&period_length=15"

Response

json

{
  "data": {
    "id": "mon_123",
    "deleted": true
  }
}

Error Codes

Code	Description
monitor_not_found	The specified monitor does not exist
invalid_request	The request parameters are invalid
rate_limit	Too many requests

Monitors API Reference ​

Authentication ​

List Monitors ​

Query Parameters ​

Response ​

Response Fields ​

Sorting ​

Search ​

Create Monitor ​

Common Parameters ​

Monitor Types ​

HTTP Monitor ​

TCP Port Monitor ​

PING Monitor ​

Keyword Monitor ​

Heartbeat Monitor ​

Response ​

Error Response ​

Get Monitor ​

Response ​

Update Monitor ​

Request Body ​

Response ​

Delete Monitor ​

Pause Monitor ​

Response ​

Resume Monitor ​

Response ​

Get Latest Transactions ​

Query Parameters ​

Response ​

Response Fields ​

Get Monitor Data ​

Query Parameters ​

Response ​

Response Fields ​

Example Use Cases ​

Response ​

Error Codes ​

Next Steps ​

Monitors API Reference

Authentication

List Monitors

Query Parameters

Response

Response Fields

Sorting

Search

Create Monitor

Common Parameters

Monitor Types

HTTP Monitor

TCP Port Monitor

PING Monitor

Keyword Monitor

Heartbeat Monitor

Response

Error Response

Get Monitor

Response

Update Monitor

Request Body

Response

Delete Monitor

Pause Monitor

Response

Resume Monitor

Response

Get Latest Transactions

Query Parameters

Response

Response Fields

Get Monitor Data

Query Parameters

Response

Response Fields

Example Use Cases

Response

Error Codes

Next Steps