Skip to main content
POST
/
live-monitor
Live Monitor
curl --request POST \
  --url https://trio.machinefi.com/api/live-monitor \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "stream_url": "<string>",
  "condition": "<string>",
  "webhook_url": "<string>",
  "interval_seconds": 10,
  "input_mode": "clip",
  "clip_duration_seconds": 3,
  "monitor_duration_seconds": 600,
  "trigger_cooldown_seconds": 0,
  "max_triggers": 1
}
'
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "<string>",
  "stream_url": "<string>",
  "job_type": "<string>",
  "details": {},
  "message": "<string>"
}
Starts a continuous job that checks a stream until your condition is met, the job is stopped, or limits are reached.

​
Key Request Fields

  • monitor_duration_seconds (default 600): per-job runtime limit in seconds.
  • trigger_cooldown_seconds (default 0): minimum seconds between trigger alerts.
  • max_triggers (default 1): number of trigger alerts before auto-stop.
    • 1 keeps legacy first-match behavior.
    • >1 allows repeated alerts, then stops.
    • null means unlimited alerts until duration/cancel.

​
Delivery Mode Selection

POST /live-monitor selects response mode by request shape:
  1. webhook_url present -> webhook mode
  2. Accept: text/event-stream and no webhook_url -> SSE mode
  3. otherwise -> polling mode

​
Response Semantics by Mode

​
Polling mode

Returns a job response (job_id, status, created_at, job_type, stream_url, optional message). Use GET /jobs/{job_id} to track runtime and terminal state.

​
Webhook mode

Returns a job response immediately, then sends async webhook events. Common webhook type values:
  • job_started
  • watch_triggered
  • job_stopped
  • error

​
SSE mode

Returns a text event stream. Common event names:
  • started
  • progress
  • triggered (non-terminal trigger event in multi-trigger mode)
  • stopped
  • error
Treat stopped and error as terminal events for that stream session. Treat triggered as non-terminal.

​
Status Semantics

For polling or post-hoc inspection:
  • running: active checks in progress
  • completed: condition matched and job completed
  • stopped: ended without failure (cancelled or auto-stop)
  • failed: ended due to runtime/stream failure
Use Get Job Details for final runtime fields. Common stop reasons in stats.reason include:
  • condition_triggered
  • max_triggers_reached
  • max_duration_reached
  • cancelled

​
Typical Usage

  1. Validate URL: Validate Stream
  2. Validate wording: Check Once
  3. Start POST /live-monitor
  4. Track via polling, webhook, or SSE

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
accept
string
default:application/json

Body

application/json

Request to start a live monitor job.

​
stream_url
string
required

YouTube Live URL or RTSP stream to monitor

Required string length: 1 - 500
​
condition
string
required

Natural language condition to watch for

Required string length: 1 - 1000
​
webhook_url
string<uri> | null

Webhook URL for notifications

Required string length: 1 - 2083
​
interval_seconds
integer
default:10

Polling interval in seconds

Required range: 5 <= x <= 300
​
input_mode
enum<string>
default:clip

Input mode: 'frames' for single frame, 'clip' for video clip, 'hybrid' for frame+clip combined

Available options:
frames,
clip,
hybrid
​
clip_duration_seconds
integer
default:3

Duration of video clip in seconds (used when input_mode is 'clip' or 'hybrid')

Required range: 1 <= x <= 10
​
monitor_duration_seconds
integer
default:600

Maximum monitoring duration in seconds

Required range: x >= 5
​
trigger_cooldown_seconds
integer
default:0

Minimum time in seconds between trigger alerts

Required range: 0 <= x <= 3600
​
max_triggers
integer | null
default:1

Maximum trigger alerts before auto-stop. Null means unlimited.

Required range: x >= 1

Response

Successful Response

Response containing job information.

​
job_id
string<uuid>
required
​
status
enum<string>
required

Job status enum.

Available options:
pending,
running,
stopped,
completed,
failed
​
created_at
string
required
​
stream_url
string
required
​
job_type
string
required
​
details
Details · object
​
message
string | null