Monitors

Watch future channel or playlist RSS uploads

Requires an API key. Creation costs zero credits. A new monitor baselines current RSS entries without historical fetches and returns 201 with idempotent:false. An account-scoped Idempotency-Key replay returns the original monitor unchanged with 200 and idempotent:true, even with changed payload fields or after cancellation; replay happens before source resolution or upstream work. An active or paused watch for the same account/channel or account/playlist also returns unchanged with 200 and idempotent:true. A new key on that source becomes an alias for the existing watch; aliases persist until the monitor/account record is deleted. Use a fresh key for a replacement after cancellation. Non-ID channel inputs use channel resolution, including its separate daily allowance and 24-hour negative cache; direct UC and playlist IDs need no resolution. Defaults: auto_fetch=false, language=en, fallback=true. One monitor per free account; 25 per paid account. Checks run at most once per 15 minutes and use a ten-minute RSS cache without proxy or Data API calls. auto_fetch creates ordinary one-video jobs; one credit is charged per successful cold transcript, zero for cache hits/failures. Monitors belong to the account and keep running after creator-key rotation, deletion, revocation, or OAuth disconnection. Automatic jobs use account daily caps, including existing key usage, rather than the creating credential's allowances. Job lists, reads, manifests, and completion events identify this work with monitor_id. Pause reasons are exactly insufficient_credits (resumes after a purchase restores enough available credits), webhook_missing (the relied-on account webhook was deleted; resumes after configuring one), and feed_unavailable (six consecutive failed feed checks; retried daily and resumed on success). Overlapping causes prioritize webhook absence, feed failure, then credits; clearing one does not bypass another. Ordinary API-key requests retain their per-key limits and may continue when monitor admission reaches its account cap. YouTube returned 404 for a well-formed channel or playlist RSS feed ID. Returns nonretryable NotFound with code feed_not_found; check the ID before retrying. Costs zero credits. Scheduled monitor polling and the monitor webhook outbox each drain until empty or their 45-second maximum, sharing a 600-operation ceiling with library backfill and rotating first priority between ten-minute ticks. Remaining work stays eligible for a later run; this is not a delivery-time guarantee.

post/v1/monitors

Request

  • Base URL: https://api.scripthaul.com
  • URL: https://api.scripthaul.com/v1/monitors
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional account-scoped replay key. Reuse it to recover the original monitor across retries or credentials; replay never changes options or restarts a cancelled watch. SDKs generate one stable key per create call unless supplied.

Request body

OR

Response

Original monitor returned unchanged for an account replay key, or existing active/paused account/source monitor. idempotent:true; costs zero credits.

okunknown required
idempotenttrue required

False for new creation (201); true for an idempotency replay or an existing live account/source watch (200).

Changes

No recorded changes to this operation across all 1 revision of this API.