Monitors API

Create Change Intelligence monitors, trigger runs, and fetch artifacts under https://cloud.meerkatagents.com/api/v1/monitors. Prefer the Ruby SDK — or call REST with Bearer auth.

The Monitor object

Monitors are always recurring. Results POST to output_webhook as signed JSON. There is no task_type field on the public API.

Field	Type	Description
`id`	integer	Unique monitor identifier.
`description`	string	Plain-English instructions for the agent.
`input_params`	object	Structured inputs (URLs, tracking links, etc.).
`frequency`	string	Schedule (e.g. `every 6 hours` or cron).
`frequency_seconds`	integer	Parsed interval in seconds (read-only).
`output_webhook`	string	HTTPS URL or `default` for your account webhook.
`output_format`	string	Webhook shape preset. Default `default`.
`status`	string	`active`, `paused`, `archived`, or `failed`.
`last_known_state`	object	Latest structured findings (on retrieve).
`last_run_at`	timestamp	When the monitor last executed.
`next_run_at`	timestamp	Next scheduled run.
`run_count`	integer	Total completed runs.
`metadata`	object	Opaque key-value metadata.

Example object

{
  "id": 42,
  "description": "Notify me when pricing or plan limits change",
  "input_params": { "url": "https://competitor.com/pricing" },
  "frequency": "every 6 hours",
  "frequency_seconds": 21600,
  "output_webhook": "https://myapp.com/webhooks/meerkat",
  "output_format": "default",
  "status": "active",
  "last_run_at": "2026-07-09T14:30:00Z",
  "next_run_at": "2026-07-09T20:30:00Z",
  "run_count": 12,
  "consecutive_failures": 0,
  "metadata": {},
  "created_at": "2026-07-01T09:00:00Z",
  "updated_at": "2026-07-09T14:30:05Z"
}

List monitors

GET https://cloud.meerkatagents.com/api/v1/monitors

Returns a paginated list of monitors for the authenticated account.

Parameters

Name	Type	In	Required	Description
`status`	string	query	No	Filter by status.
`include_archived`	boolean	query	No	Include archived monitors. Default `false`.
`limit`	integer	query	No	Page size (1–200). Default `50`.
`offset`	integer	query	No	Pagination offset. Default `0`.

Returns

200 OK Paginated list of monitors.

{
  "data": [{ "id": 42, "description": "Notify me when pricing…", "status": "active" }],
  "meta": { "limit": 50, "offset": 0, "count": 1, "total": 1 }
}

Create a monitor

POST https://cloud.meerkatagents.com/api/v1/monitors

Registers a recurring monitor. Set output_webhook to default to use your account default webhook.

curl

curl -X POST https://cloud.meerkatagents.com/api/v1/monitors \
  -H "Authorization: Bearer $MEERKAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor": {
      "description": "Notify me when pricing or plan limits change",
      "input_params": { "url": "https://competitor.com/pricing" },
      "frequency": "every 6 hours",
      "output_webhook": "https://myapp.com/webhooks/meerkat",
      "run_immediately": true
    }
  }'

Ruby

client.monitors.create(
  description: "Notify me when pricing or plan limits change",
  input_params: { url: "https://competitor.com/pricing" },
  frequency: "every 6 hours",
  output_webhook: "https://myapp.com/webhooks/meerkat"
)

Retrieve a monitor

GET https://cloud.meerkatagents.com/api/v1/monitors/{id}

Retrieves a monitor by ID, including last_known_state from the most recent run.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.

Returns

200 OK Monitor with current state.

{ "data": { "id": 42, "status": "active", "last_known_state": {} } }

Update a monitor

PATCH https://cloud.meerkatagents.com/api/v1/monitors/{id}

Updates monitor fields. Send only the attributes to change.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.
`monitor`	object	body	Yes	Fields to update.

Request body

{
  "monitor": {
    "frequency": "every 12 hours",
    "description": "Watch pricing and plan limits"
  }
}

Returns

200 OK Updated monitor.

{ "data": { "id": 42, "frequency": "every 12 hours" } }

Delete a monitor

DELETE https://cloud.meerkatagents.com/api/v1/monitors/{id}

Archives (or permanently deletes with permanent=true) a monitor.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.
`permanent`	boolean	query	No	Hard delete. Default `false`.

Returns

204 No Content Deleted.

Run a monitor

POST https://cloud.meerkatagents.com/api/v1/monitors/{id}/run

Enqueues (or sync-runs) a monitor. Consumes one run credit.

curl

curl -X POST https://cloud.meerkatagents.com/api/v1/monitors/42/run \
  -H "Authorization: Bearer $MEERKAT_API_KEY"

Pause a monitor

POST https://cloud.meerkatagents.com/api/v1/monitors/{id}/pause

Stops the schedule until resumed.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.

Returns

200 OK Paused monitor.

{ "data": { "id": 42, "status": "paused" } }

Resume a monitor

POST https://cloud.meerkatagents.com/api/v1/monitors/{id}/resume

Reactivates a paused monitor and may enqueue a run.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.

Returns

200 OK Active monitor.

{ "data": { "id": 42, "status": "active" } }

List runs

GET https://cloud.meerkatagents.com/api/v1/monitors/{id}/runs

Recent runs for a monitor. Each run includes artifacts (structured findings).

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.
`limit`	integer	query	No	Max runs (default 20).

Returns

200 OK Run list.

{ "data": [{ "id": 9, "monitor_id": 42, "status": "succeeded", "artifacts": {} }], "meta": {} }

Retrieve a run

GET https://cloud.meerkatagents.com/api/v1/monitors/{id}/runs/{run_id}

Fetch one run including artifacts and usage.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.
`run_id`	integer	path	Yes	Run ID.

Returns

200 OK Run object.

{ "data": { "id": 9, "monitor_id": 42, "artifacts": { "summary": "…" } } }

Run artifacts

GET https://cloud.meerkatagents.com/api/v1/monitors/{id}/runs/{run_id}/artifacts

Convenience endpoint for structured findings from a run.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.
`run_id`	integer	path	Yes	Run ID.

Returns

200 OK Artifacts payload.

{ "data": { "run_id": 9, "monitor_id": 42, "artifacts": {} } }

List events

GET https://cloud.meerkatagents.com/api/v1/monitors/{id}/events

Webhook delivery and lifecycle events for a monitor.

Parameters

Name	Type	In	Required	Description
`id`	integer	path	Yes	Monitor ID.

Returns

200 OK Event list.

{ "data": [{ "id": 1, "event_type": "webhook_delivered", "monitor_id": 42 }] }

Legacy: /api/v1/tasks still works for older clients — prefer /monitors. See also the OpenAPI spec.