Schedule Reddit Posts and Comments Through the API

Schedule a post or a comment to be made later. At the time you choose, the request runs through the same route a live call uses, POST /api/reddit/submit or POST /api/reddit/comment, as your stored Reddit session.

• Needs a stored session. Connect it once with POST /api/reddit/session. Scheduling is refused while none is connected, and an action runs with the session connected when it runs: if Reddit logged it out in between, the run fails and is not charged.
• No cookies, no proxy. A scheduled request never carries or stores cookies or a proxy. Both are refused with SESSION_FIELDS_NOT_STORED.
• Billed when it runs. Scheduling, listing and cancelling are free. A run that succeeds is charged at the live route's price ($0.012), to the API key that scheduled it. A run that fails is not charged, and a cancelled action never runs.
• Timing. run_at is 60 seconds to 30 days ahead. Due actions are picked up every 30 seconds and run one at a time, so an action normally runs within about a minute of run_at, later when many fall due together. Up to 100 actions can wait per account.
• Never retried. A run that fails is recorded as failed with Reddit's reason. A run that got no answer within 10 minutes is failed with EXECUTION_UNCONFIRMED (or EXECUTION_INTERRUPTED after a restart), because it may still have posted, and been charged: its billed is null (unknown). Check the subreddit and your usage history before scheduling it again.

Schedule

request for a post takes the submit fields: subreddit, kind (self, link or poll), title, and optionally text, url, options, duration, nsfw, spoiler, sendreplies, flair_id, flair_text, locale, timezone, fingerprint. List a subreddit's flair ids with GET /api/reddit/sub/:name/flairs.

request for a comment takes the comment fields: post_url, text, and optionally locale, timezone, fingerprint.

Any other field is refused with a 400 naming it. The required fields, types and lengths are checked now; everything else the live route checks (poll options, Reddit's own subreddit rules) is checked when it runs.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://api.redditapis.com/api/reddit/schedule" \
  -d '{
    "type": "post",
    "run_at": "2026-10-21T15:00:00Z",
    "request": {
      "subreddit": "SaaS",
      "kind": "self",
      "title": "What we learned shipping our first API",
      "text": "Three things surprised us...",
      "flair_id": "a1b2c3d4-0000-11ee-8000-000000000001"
    }
  }'

The answer is 201 Created with the new action:

{
  "action": {
    "id": "5f0c2a8e-8f3e-4c0b-9d0a-2b7d1c6e9a11",
    "type": "post",
    "status": "scheduled",
    "run_at": "2026-10-21T15:00:00.000Z",
    "request": { "subreddit": "SaaS", "kind": "self", "title": "What we learned shipping our first API", "text": "Three things surprised us...", "flair_id": "a1b2c3d4-0000-11ee-8000-000000000001" },
    "created_at": "2026-10-20T18:02:11.000Z",
    "finished_at": null,
    "result": null,
    "error": null,
    "billed": false
  }
}

List

Returns actions (newest first) and count.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.redditapis.com/api/reddit/schedule?status=scheduled"

Cancel

Returns cancelled: true and the action when it had not run yet. An action that already ran, or is running, returns cancelled: false with its current status, and nothing changes. An id that is not on your account is a 404.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://api.redditapis.com/api/reddit/schedule/cancel" \
  -d '{"id": "5f0c2a8e-8f3e-4c0b-9d0a-2b7d1c6e9a11"}'

Action Fields

Errors

Failed runs carry the live route's own code in error.code, for example NOT_ALLOWED_IN_SUBREDDIT, REDDIT_RATELIMIT or CAPTCHA_REQUIRED from submit, and HTTP_402 when the account was out of credits when it ran. A run stopped by CAPTCHA_REQUIRED says so in plain words in error.message: Reddit wanted a captcha first, so nothing was posted.