Check a Reddit Subreddit for Updates

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

Check the subreddit now and record new or updated posts. A completed check costs 5 Credits plus 2 Credits per unique new-or-updated post; 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/reddit/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 Reddit monitor check result.

application/json

RedditMonitorCheckResponse

monitor RedditMonitor required
events array of RedditMonitorEvent 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 Reddit 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.

RedditMonitorCheckResponse

object

monitor RedditMonitor required
events array of RedditMonitorEvent required

Complete schema

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

RedditMonitor

object

id string required
platform string required: Allowed: "reddit"
status string required: Allowed: "active", "paused"
strategy RedditMonitorStrategy required
target RedditMonitorTarget required
settings RedditMonitorSettings required
checks array of RedditMonitorCheckState 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": [
        "reddit"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    },
    "strategy": {
      "$ref": "#/components/schemas/RedditMonitorStrategy"
    },
    "target": {
      "$ref": "#/components/schemas/RedditMonitorTarget"
    },
    "settings": {
      "$ref": "#/components/schemas/RedditMonitorSettings"
    },
    "checks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/RedditMonitorCheckState"
      }
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

RedditMonitorStrategy

string

Complete schema

{
  "type": "string",
  "enum": [
    "json_fetch"
  ]
}

RedditMonitorTarget

object

subreddit string required
target_url string | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "subreddit"
  ],
  "properties": {
    "subreddit": {
      "type": "string"
    },
    "target_url": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

RedditMonitorSettings

object

check_interval_seconds number required
max_items integer required
quiet_first_check boolean required
quiet_start boolean required
sort RedditListingSort required
time_filter string | null
warmup_cookie_max_age_seconds integer required
comment_collection RedditMonitorCommentCollection or null
event_webhook SourceMonitorEventWebhookStatus or null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "check_interval_seconds",
    "max_items",
    "quiet_first_check",
    "quiet_start",
    "sort",
    "warmup_cookie_max_age_seconds"
  ],
  "properties": {
    "check_interval_seconds": {
      "type": "number"
    },
    "max_items": {
      "type": "integer"
    },
    "quiet_first_check": {
      "type": "boolean"
    },
    "quiet_start": {
      "type": "boolean"
    },
    "sort": {
      "$ref": "#/components/schemas/RedditListingSort"
    },
    "time_filter": {
      "type": [
        "string",
        "null"
      ]
    },
    "warmup_cookie_max_age_seconds": {
      "type": "integer"
    },
    "comment_collection": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/RedditMonitorCommentCollection"
        },
        {
          "type": "null"
        }
      ]
    },
    "event_webhook": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/SourceMonitorEventWebhookStatus"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

RedditListingSort

string

Complete schema

{
  "type": "string",
  "enum": [
    "hot",
    "new",
    "top",
    "rising"
  ]
}

RedditMonitorCommentCollection

object

on_new_posts boolean

Default: false

on_updated_posts boolean

Default: false

sort string

Allowed: "confidence", "top", "new", "controversial", "old", "qa"

Default: "confidence"

max_comments integer

Default: 500

max_depth integer

Default: 10

expand_more boolean

Default: true

min_num_comments integer

Default: 1

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "on_new_posts": {
      "type": "boolean",
      "default": false
    },
    "on_updated_posts": {
      "type": "boolean",
      "default": false
    },
    "sort": {
      "type": "string",
      "enum": [
        "confidence",
        "top",
        "new",
        "controversial",
        "old",
        "qa"
      ],
      "default": "confidence"
    },
    "max_comments": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "default": 500
    },
    "max_depth": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 10
    },
    "expand_more": {
      "type": "boolean",
      "default": true
    },
    "min_num_comments": {
      "type": "integer",
      "minimum": 0,
      "default": 1
    }
  }
}

SourceMonitorEventWebhookStatus

object

url string required
enabled boolean required
secret_configured boolean required
event_types array of string

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url",
    "enabled",
    "secret_configured"
  ],
  "properties": {
    "url": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "secret_configured": {
      "type": "boolean"
    },
    "event_types": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      }
    }
  }
}

RedditMonitorCheckState

object

strategy RedditMonitorStrategy 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/RedditMonitorStrategy"
    },
    "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"
      ]
    }
  }
}

RedditMonitorEvent

object

id string required
type string required: Allowed: "new_post", "updated_post", "comment_job_enqueued", "monitor_error"
monitor_id string required
strategy RedditMonitorStrategy or null
post_id string | null
post RedditPost or null
previous_post RedditPost or null
error RedditMonitorEventError or null
comment_job_id string | 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_post",
        "updated_post",
        "comment_job_enqueued",
        "monitor_error"
      ]
    },
    "monitor_id": {
      "type": "string"
    },
    "strategy": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/RedditMonitorStrategy"
        },
        {
          "type": "null"
        }
      ]
    },
    "post_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "post": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/RedditPost"
        },
        {
          "type": "null"
        }
      ]
    },
    "previous_post": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/RedditPost"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/RedditMonitorEventError"
        },
        {
          "type": "null"
        }
      ]
    },
    "comment_job_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "observed_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

RedditPost

object

fullname string required
post_id string required
subreddit string required
url string required
title string required
author string | null
selftext string | null
published_at string | null (date-time)
score integer | null
num_comments integer | null
first_seen_at string | null (date-time)
last_seen_at string | null (date-time)

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "fullname",
    "post_id",
    "subreddit",
    "url",
    "title"
  ],
  "properties": {
    "fullname": {
      "type": "string"
    },
    "post_id": {
      "type": "string"
    },
    "subreddit": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "author": {
      "type": [
        "string",
        "null"
      ]
    },
    "selftext": {
      "type": [
        "string",
        "null"
      ]
    },
    "published_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "score": {
      "type": [
        "integer",
        "null"
      ]
    },
    "num_comments": {
      "type": [
        "integer",
        "null"
      ]
    },
    "first_seen_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "last_seen_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

RedditMonitorEventError

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
    }
  }
}