/monitors/{id} (GET)

GET

/monitors/{id}

const url = 'https://culipulse.dev/v1/monitors/mon_123';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://culipulse.dev/v1/monitors/mon_123 \
  --header 'Authorization: Bearer <token>'

Authorizations

bearerAuth
read

Parameters

Path Parameters

required

string

Example

mon_123

Responses

200

Monitor detail

application/json

object

required

string

name

required

string

type

required

string

Allowed values: http tcp icmp udp domain heartbeat dns vendor

target

required

string

interval_seconds

required

integer

timeout_ms

required

integer

method

required

string | null

expected_status

required

string | null

body_match

required

string | null

follow_redirects

required

1 = follow redirects, 0 = don’t

integer

down_after_failures

required

Consecutive failed checks before the monitor is marked down. Ignored for heartbeat monitors: a heartbeat goes down at the first missed deadline (use grace_seconds to allow lateness).

integer

up_after_successes

required

Consecutive successful checks before a down monitor is marked up again. Ignored for heartbeat monitors: a heartbeat is up again at its first ping.

integer

down_min_sources

required

How many agents must see a failure before the monitor is marked down. If fewer agents are reporting than this, the agents that are reporting decide, and deleting an agent lowers this to the agents that remain. Only used by monitors that check from agents (http, tcp, icmp, udp); vendor, domain and dns are checked once by CuliPulse, so it is always 1 for them.

integer

heartbeat_grace_seconds

required

Heartbeat only. Written as grace_seconds.

integer | null

sla_target

required

number | null

status

required

string

Allowed values: up down degraded paused pending

enabled

required

1 = being checked, 0 = paused. Change it with POST /monitors/{id}/pause and /monitors/{id}/resume.

integer

created_at

required

Unix seconds

integer

updated_at

required

Unix seconds

integer

check_spec

Returned by GET /monitors/{id}; omitted from the list.

object

request

HTTP monitors: what to send.

object

headers

Plain request headers. Up to 50 headers in total (plain + secret), names up to 256 characters, values up to 8192 characters. The whole check_spec may be at most 128 KB.

object

<= 50 properties

key

additional properties

string

<= 8192 characters

secretHeaders

Write-only. Headers stored encrypted; reads return their names in secretHeaderNames. Send {} to clear. Same limits as headers.

object

<= 50 properties

key

additional properties

string

<= 8192 characters

preserveSecretHeaders

Write-only. true keeps the stored secret headers.

boolean

secretHeaderNames

Read-only. Names of the stored secret headers.

Array<string>

auth

Reads return type only. Send type alone to keep the stored credentials.

object

type

string

Allowed values: bearer basic

token

string

username

string

password

string

body

Request body, up to 65,536 characters.

string

<= 65536 characters

bodySecret

On write, stores body encrypted. On read, true means a secret body is set (it isn’t returned).

boolean

preserveBody

Write-only, with bodySecret: true keeps the stored secret body.

boolean

contentType

string

assertions

HTTP monitors: extra checks on the response.

Array<object>

object

source

string

Allowed values: text_body json_body header response_time cert_expiry

string

value

string

path

Json_body only.

string

name

Header only.

string

transport

TCP and UDP monitors: what to send and expect (the expected reply is the banner check).

object

payload

What to send, up to 1,024 bytes. With payloadEncoding utf8 (the default) these escapes are turned into real characters when the check runs: \r, \n, \t, \xHH (00 to 7F) and \\ for one backslash, so PING\r\n sends PING and a line break. Any other backslash is sent as typed. With hex it is a hex string (0d0a is a line break) and nothing is interpreted.

string

payloadEncoding

string

Allowed values: utf8 hex

expect

string

expectMode

string

Allowed values: contains regex

payloadSecret

On write, stores payload encrypted. On read, true means a secret payload is set.

boolean

preservePayload

Write-only, with payloadSecret: true keeps the stored secret payload.

boolean

domain

Days of warning before a domain or certificate expires.

object

warnDays

integer

ping

ICMP monitors.

object

count

integer

lossDegradedPct

integer

rttDegradedMs

integer

heartbeat

Heartbeat monitors. The server creates the token and keeps it on update.

object

token

The secret in the monitor’s ping URL: https://culipulse.dev/ping/<token> (add /start, /fail, or an exit code such as /0 to the end). Anyone who has it can check the monitor in or mark it down, so it is returned only to tokens with the write scope; with a read-only token it is left out.

string

failEnabled

Always true. /fail, or a check-in with a non-zero exit code (such as /2), always marks the monitor down; that can’t be turned off. A bare ping or /start doesn’t. Sending false is a 400.

boolean

maxDurationSeconds

Run-time limit in seconds, measured from the job’s /start ping to its finishing ping. It only applies to runs that send /start. A run with no finishing ping by the limit is flagged (degraded) at that moment. 0 or omitted means no limit.

integer

dns

DNS monitors.

object

records

Array<object>

object

type

string

mode

string

expected

Array<string>

crossCheck

boolean

vendor

Read-only. Vendor status monitors: set by the server from target.

object

vendorId

string

pageUrl

string

probeUrl

string

components

Array<string>

dependencies

Read-only. Ids of the vendor monitors this monitor depends on.

Array<string>

agent_sources

Agent ids probing this monitor. Returned by GET /monitors/{id}.

Array<string>

per_region

The latest result from each location that checks this monitor. Returned by GET /monitors/{id}, and by pause and resume; omitted from the list. Only symptom is documented so far: each entry carries more fields that are not part of the stable contract yet.

Array<object>

object

symptom

Plain-words reason this location’s latest check failed. Present only when that check failed with a known reason; absent when it passed. The wording is for people to read and can change, so don’t match on it.

string

coverage

Present on GET /monitors/{id}. Set only when a monitor checks from two or more agents and some, but not all, are reporting: the agents listed in silent are not contributing, so until they are back the monitor is judged by the ones that are (a single agent can then mark it down). Null otherwise (all reporting, none reporting, paused, or a single agent).

object

reporting

required

How many of the monitor’s agents sent a result at the last check.

integer

total

required

How many agents the monitor checks from.

integer

silent

required

The agents that did not report.

Array<object>

object

required

string

name

required

string

last_seen_at

required

Unix seconds the agent last checked in with CuliPulse, or null if it never has.

integer | null

reason

required

offline: the agent has not checked in recently. not_sending: the agent is online but sent no usable result for this monitor.

string

Allowed values: offline not_sending

Example

{
  "id": "mon_123",
  "type": "http",
  "status": "up",
  "check_spec": {
    "request": {
      "auth": {
        "type": "bearer"
      }
    },
    "assertions": [
      {
        "source": "text_body"
      }
    ],
    "transport": {
      "payloadEncoding": "utf8",
      "expectMode": "contains"
    }
  },
  "per_region": [
    {
      "symptom": "Couldn't connect — port closed or refused"
    }
  ],
  "coverage": {
    "silent": [
      {
        "reason": "offline"
      }
    ]
  }
}

401

Unauthorized

application/json

object

error

required

string

request_id

string

code

Present on some 400s so a client can branch without parsing error. Known values: channel_limit_reached, too_many_monitors, duplicate_webhook_url.

string

field

The request field the error is about, when there is one.

string

limit

The limit that was hit, when code names one.

integer

Example

{
  "error": "not found",
  "request_id": "req_abc123",
  "code": "channel_limit_reached"
}

404

Not found

application/json

object

error

required

string

request_id

string

code

Present on some 400s so a client can branch without parsing error. Known values: channel_limit_reached, too_many_monitors, duplicate_webhook_url.

string

field

The request field the error is about, when there is one.

string

limit

The limit that was hit, when code names one.

integer

Example

{
  "error": "not found",
  "request_id": "req_abc123",
  "code": "channel_limit_reached"
}