---
title: "Watch future channel or playlist RSS uploads"
method: POST
path: "/v1/monitors"
tags: ["Monitors"]
---

# Watch future channel or playlist RSS uploads

`POST /v1/monitors`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `channel` string, required: UC channel ID, public channel URL, or handle. Non-ID inputs resolve on the server through the channel-resolution daily allowance (including warm resolutions) and 24-hour negative cache; direct UC IDs need no resolution call.
    - `playlist` string: Public playlist ID or URL.
    - `auto_fetch` boolean: Create ordinary single-video transcript jobs for future unseen uploads, under account daily caps. Successful cold delivery costs one credit; cache hits and failures are free. The account watch continues after creator-key changes or OAuth disconnection. Ordinary API-key requests retain their per-key limits and may continue when monitor admission reaches its account cap.
    - `language` string
    - `fallback` boolean
    - `webhook_url` string, uri: Optional public HTTPS destination using the configured account webhook signing secret. Deleting that signing configuration pauses a dependent monitor with webhook_missing until an account webhook is configured again. A monitor created without a webhook adopts the account webhook when one is configured; before that it may continue checking and fetching without notifications.
  - object
    - `channel` string: UC channel ID, public channel URL, or handle. Non-ID inputs resolve on the server through the channel-resolution daily allowance (including warm resolutions) and 24-hour negative cache; direct UC IDs need no resolution call.
    - `playlist` string, required: Public playlist ID or URL.
    - `auto_fetch` boolean: Create ordinary single-video transcript jobs for future unseen uploads, under account daily caps. Successful cold delivery costs one credit; cache hits and failures are free. The account watch continues after creator-key changes or OAuth disconnection. Ordinary API-key requests retain their per-key limits and may continue when monitor admission reaches its account cap.
    - `language` string
    - `fallback` boolean
    - `webhook_url` string, uri: Optional public HTTPS destination using the configured account webhook signing secret. Deleting that signing configuration pauses a dependent monitor with webhook_missing until an account webhook is configured again. A monitor created without a webhook adopts the account webhook when one is configured; before that it may continue checking and fetching without notifications.

## Response `200`

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

- MonitorReplayed
  - `ok` unknown, required
  - `monitor` Monitor, required: 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. Ordinary API-key requests retain their per-key limits and may continue when monitor admission reaches its account cap.
    - `id` string, required
    - `channel_id` string, nullable, required
    - `playlist_id` string, nullable, required
    - `language` string, required
    - `fallback` boolean, required
    - `auto_fetch` boolean, required
    - `webhook_url` string, nullable, required
    - `status` 'active' | 'paused' | 'cancelled', required
    - `pause_reason` 'insufficient_credits' | 'webhook_missing' | 'feed_unavailable' | 'null', nullable, required: 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.
    - `last_checked_at` string, nullable, required
    - `last_video_published_at` string, nullable, required
    - `created_at` string, required
    - `cancelled_at` string, nullable, required
    - `new_video_count` integer, required
    - `last_error` string, nullable, required: Latest bounded feed-error summary; null after a successful feed check.
    - `consecutive_failures` integer, required: Consecutive failed feed checks. Six failures pause for feed_unavailable; a successful check resets the count.
  - `idempotent` true, required: False for new creation (201); true for an idempotency replay or an existing live account/source watch (200).

## Other responses

- `201`: New monitor created, current feed baselined, idempotent:false. Costs zero credits.
- `400`: InvalidInput: malformed source/options, blank or overlong Idempotency-Key, or invalid/unconfigured webhook override. Costs zero credits.
- `401`: Forbidden: a Bearer API key is missing, malformed, unknown, or revoked. Dashboard cookies cannot authenticate this endpoint. Costs zero credits.
- `403`: AccountFrozen or Forbidden: the account is frozen or the authenticated caller cannot use this route. Costs zero credits.
- `404`: NotFound feed_not_found when the public RSS baseline returns 404; InvalidInput when channel resolution confirms a missing channel (24-hour negative cache). Costs zero credits.
- `429`: QuotaExceeded: account monitor limit, request rate, channel-resolution allowance or upstream capacity exhausted. Costs zero credits.
- `502`: UpstreamError: the RSS baseline could not be fetched. No monitor delivery charge.
- `503`: ConfigurationError: required service configuration is unavailable. Costs zero credits.

---

[API](https://skmtc.dev/scripthaul/apis/scripthaul-api.md) · [All operations](https://skmtc.dev/scripthaul/apis/scripthaul-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scripthaul/apis/scripthaul-api/revisions/f476d69f4a6b?raw)