Check a YouTube Channel for Updates

POST/v1/youtube/monitors/{monitor_id}/check

Runs the monitor's configured backend strategies immediately. For auto, RSS and yt-dlp polling both run as peer strategies. A completed check costs 5 Credits plus 2 Credits per unique new-or-updated video; failed checks are released without charge.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/youtube/monitors/{monitor_id}/check" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01'

Authentication

BearerAuth

Parameters

monitor_id path · string required
Idempotency-Key header · string: Caller-generated key, up to 128 characters, that identifies one API Market write and its billing event. Reuse the same key only when retrying the same logical request. Replays do not create another reservation or capture.

Responses

200 YouTube monitor check result.

application/json

YoutubeMonitorCheckResponse

monitor YoutubeMonitor required
events array of YoutubeMonitorEvent required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

404 YouTube monitor was not found or is not visible to this workspace.

application/json

PublicErrorResponse

error PublicError required

409 Billing settlement requires reconciliation, or the idempotency key was reused for a different logical request.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

YoutubeMonitorCheckResponse

object

monitor YoutubeMonitor required
events array of YoutubeMonitorEvent required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "monitor",
    "events"
  ],
  "properties": {
    "monitor": {
      "$ref": "#/components/schemas/YoutubeMonitor"
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/YoutubeMonitorEvent"
      }
    }
  }
}

YoutubeMonitor

object

id string required
platform string required: Allowed: "youtube"
status string required: Allowed: "active", "paused"
strategy YoutubeMonitorStrategy required
target YoutubeMonitorTarget required
settings YoutubeMonitorSettings required
checks array of YoutubeMonitorCheckState required
created_at string | null (date-time)
updated_at string | null (date-time)

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "platform",
    "status",
    "strategy",
    "target",
    "settings",
    "checks"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "youtube"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    },
    "strategy": {
      "$ref": "#/components/schemas/YoutubeMonitorStrategy"
    },
    "target": {
      "$ref": "#/components/schemas/YoutubeMonitorTarget"
    },
    "settings": {
      "$ref": "#/components/schemas/YoutubeMonitorSettings"
    },
    "checks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/YoutubeMonitorCheckState"
      }
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

YoutubeMonitorStrategy

string

Complete schema

{
  "type": "string",
  "enum": [
    "rss",
    "yt_dlp_polling",
    "auto"
  ]
}

YoutubeMonitorTarget

object

channel_id string | null
channel_url string | null
rss_url string | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "channel_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "channel_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "rss_url": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

YoutubeMonitorSettings

object

check_interval_seconds number required
slow_check_interval_seconds number required
max_items integer required
quiet_first_check boolean required
quiet_start boolean required
track_reschedule boolean required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "check_interval_seconds",
    "slow_check_interval_seconds",
    "max_items",
    "quiet_first_check",
    "quiet_start",
    "track_reschedule"
  ],
  "properties": {
    "check_interval_seconds": {
      "type": "number"
    },
    "slow_check_interval_seconds": {
      "type": "number"
    },
    "max_items": {
      "type": "integer"
    },
    "quiet_first_check": {
      "type": "boolean"
    },
    "quiet_start": {
      "type": "boolean"
    },
    "track_reschedule": {
      "type": "boolean"
    }
  }
}

YoutubeMonitorCheckState

object

strategy YoutubeMonitorBackendStrategy required
status string required: Allowed: "never_run", "completed", "failed", "not_modified"
next_check_at string | null (date-time)
last_checked_at string | null (date-time)
last_error_code string | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "strategy",
    "status"
  ],
  "properties": {
    "strategy": {
      "$ref": "#/components/schemas/YoutubeMonitorBackendStrategy"
    },
    "status": {
      "type": "string",
      "enum": [
        "never_run",
        "completed",
        "failed",
        "not_modified"
      ]
    },
    "next_check_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_checked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_error_code": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

YoutubeMonitorBackendStrategy

string

Complete schema

{
  "type": "string",
  "enum": [
    "rss",
    "yt_dlp_polling"
  ]
}

YoutubeMonitorEvent

object

id string required
type string required: Allowed: "new_video", "updated_video", "rescheduled_video", "monitor_error"
monitor_id string required
strategy YoutubeMonitorBackendStrategy or null
video_id string | null
video YoutubeVideo or null
previous_video YoutubeVideo or null
error YoutubeMonitorEventError or null
observed_at string (date-time) required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "monitor_id",
    "observed_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "new_video",
        "updated_video",
        "rescheduled_video",
        "monitor_error"
      ]
    },
    "monitor_id": {
      "type": "string"
    },
    "strategy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/YoutubeMonitorBackendStrategy"
        },
        {
          "type": "null"
        }
      ]
    },
    "video_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "video": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/YoutubeVideo"
        },
        {
          "type": "null"
        }
      ]
    },
    "previous_video": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/YoutubeVideo"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/YoutubeMonitorEventError"
        },
        {
          "type": "null"
        }
      ]
    },
    "observed_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

YoutubeVideo

object

video_id string required
url string required
title string required
description string | null
thumbnail_url string | null
published_at string | null (date-time)
scheduled_at string | null (date-time)
updated_at string | null (date-time)
channel_id string | null
author string | null
live_status string | null
view_count integer | null
first_seen_at string | null (date-time)
last_seen_at string | null (date-time)

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "video_id",
    "url",
    "title"
  ],
  "properties": {
    "video_id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "thumbnail_url": {
      "type": [
        "string",
        "null"
      ]
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "scheduled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "channel_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "author": {
      "type": [
        "string",
        "null"
      ]
    },
    "live_status": {
      "type": [
        "string",
        "null"
      ]
    },
    "view_count": {
      "type": [
        "integer",
        "null"
      ]
    },
    "first_seen_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_seen_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

YoutubeMonitorEventError

object

code string required
message string required
retryable boolean required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}