Flow Monitors

List All Flow Monitors

Retrieves your team's flow monitors, most recently created first.

This endpoint is paginated. See Pagination for how to page through the full list.

Required scope: flow-monitors:read

Query Parameters

• perPageinteger

  Results per page, 1-200 (default: 50)

• cursorstring

  Page to fetch, taken from a Link header

Create a Flow Monitor

Creates a flow monitor. The spec is checked before anything is stored: it has to parse, and every host it names has to be covered by one of the team's verified domains. A refused create leaves no row behind.

A new monitor is scheduled for its first run on the next cron tick, so it reports a status straight away rather than after one silent interval.

The response is 201 Created.

Required scope: flow-monitors:write

Request Body

• namestringRequired

  Monitor name (1-255 characters)

• sourcestringRequired

  The spec text, up to 20000 characters. Stored, never returned.

• intervalSecondsinteger

  One of 900, 1800, 3600, 10800, 21600, 43200, 86400 (default: 3600)

• isEnabledboolean

  Whether the flow runs on its interval (default: true)

The spec you just sent is not echoed back.

Rejected: an interval that is not on the list

curl https://uptime.sergiodxa.com/api/v1/flow-monitors \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Every minute", "source": "...", "intervalSeconds": 60 }'

{
	"type": "https://uptime.sergiodxa.com/docs/api/errors/validation-error",
	"title": "The request failed validation",
	"status": 400,
	"instance": "urn:uuid:0b6a4c1e-3f7d-4e8a-9c21-5d8f0a7b3e64",
	"errors": [
		{
			"pointer": "/intervalSeconds",
			"code": "invalid",
			"message": "Expected one of: 900, 1800, 3600, 10800, 21600, 43200, 86400"
		}
	]
}

Rejected: a host no verified domain covers

curl https://uptime.sergiodxa.com/api/v1/flow-monitors \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Somebody else s site",
    "source": "use http\ntest \"reaches elsewhere\" {\n\twhen {\n\t\tlet response = http.get \"https://victim.example.net/login\"\n\t}\n}"
  }'

{
	"type": "https://uptime.sergiodxa.com/docs/api/errors/validation-error",
	"title": "The request failed validation",
	"status": 400,
	"detail": "This flow reaches victim.example.net, which no verified domain on this team covers. A flow monitor can only drive a domain the team has verified.",
	"instance": "urn:uuid:0b6a4c1e-3f7d-4e8a-9c21-5d8f0a7b3e64",
	"errors": [
		{
			"pointer": "/source",
			"code": "invalid",
			"message": "This flow reaches victim.example.net, which no verified domain on this team covers. A flow monitor can only drive a domain the team has verified."
		}
	]
}

A spec that names no host at all is refused the same way, with:

{
	"type": "https://uptime.sergiodxa.com/docs/api/errors/validation-error",
	"title": "The request failed validation",
	"status": 400,
	"detail": "This flow names no host to reach. Every URL it requests has to be written in the spec, so it can be checked against the team's verified domains.",
	"instance": "urn:uuid:0b6a4c1e-3f7d-4e8a-9c21-5d8f0a7b3e64",
	"errors": [
		{
			"pointer": "/source",
			"code": "invalid",
			"message": "This flow names no host to reach. Every URL it requests has to be written in the spec, so it can be checked against the team's verified domains."
		}
	]
}

Get a Flow Monitor

Retrieves a single flow monitor by ID.

Required scope: flow-monitors:read

A monitor belonging to another team is 404, not 403: an id you may not read is an id that does not exist.

The detail response carries no more than the list response does: source is withheld from both, so neither is the place to read a spec back.

Update a Flow Monitor

Updates a flow monitor with a JSON merge patch. Every field is optional; only the ones you send change.

A new source replaces the spec, and the replacement goes through the same verified-domain check a create does. Changing intervalSeconds or isEnabled reschedules the monitor in the same write, so the next run honours the new setting rather than the old one.

Required scope: flow-monitors:write

Request Body

The fields and limits are Create a Flow Monitor's. null resets intervalSeconds and isEnabled to their defaults; name and source cannot be removed.

• namestring

  Monitor name (1-255 characters)

• sourcestring

  Replacement spec text, up to 20000 characters

• intervalSecondsinteger

  One of 900, 1800, 3600, 10800, 21600, 43200, 86400

• isEnabledboolean

  Whether the flow runs on its interval

A refused update changes nothing: the stored spec, interval and schedule are exactly what they were before the call.

Update With PUT

PUT /api/v1/flow-monitors/:flowMonitorId takes the same fields, for integrations written before PATCH existed. A field you leave out keeps its value, null is refused, a source you send goes through the verified-domain check even when it is unchanged, and isEnabled: true schedules an immediate run on every request.

Required scope: flow-monitors:write

Delete a Flow Monitor

Permanently deletes a flow monitor, its spec, and its run history.

Required scope: flow-monitors:delete

Get Flow Monitor Results

Retrieves the run history for a flow monitor: one row per run, however many requests that run made. Newest first.

Runs arrive a page at a time. See Pagination for how to walk the whole history.

Required scope: flow-monitors:read

Query Parameters

• perPageinteger

  Results per page, 1-200 (default: 50)

• cursorstring

  Page to fetch, taken from a Link header

Only the first failure of a run is recorded, in failedTest, failedAtLine and failureDetail. That is the one worth reading during an incident: once a sign-in breaks, everything after it fails for the same reason.

requestsMade is what the run cost. A flow is metered as one ping per request it performed, so a three-request flow on the hourly interval bills like three hourly HTTP monitors.

durationMs is the wall-clock of the whole run, which is also this monitor's latency series.