Skip to content

README.md

Latest commit

 

History

History
125 lines (93 loc) · 5.69 KB

README.md

File metadata and controls

125 lines (93 loc) · 5.69 KB
Raw

Reddit Comments API examples for SocQ

Reddit Comments API API documentation License: MIT Check examples

Collect public Reddit comments from post URLs, returning text, author and thread context, timestamps, and visible engagement in normalized records.

Try Reddit Comments API · Get an API key · Documentation · All SocQ examples

Use cases

  • Qualitative response review: Analyze comment text with available author fields to identify arguments, questions, and recurring reactions within selected discussions.
  • Returned reply relationship mapping: Use comment IDs and parent_comment_id to connect replies that are present in the returned records without assuming the full thread was captured.
  • Source-linked comment archiving: Preserve comment URLs, post_id, post_url, community_name, and timestamps so every saved reply retains its discussion context.
  • Time-stamped response comparison: Compare upvotes_count and replies_count across returned comments while anchoring each observation to collected_at.

API behavior

  • Submit public Reddit post URLs using /r/{subreddit}/comments/{post_id} paths or supported redd.it short links.
  • This endpoint does not accept results_limit; it stores the publicly returned comments for each accepted post URL.
  • Parent and source-post references connect returned records without guaranteeing complete thread depth.
  • Upvote and reply counts are point-in-time observations captured at collected_at.

All requests use the shared asynchronous flow:

submit -> task_id -> poll task -> read every cursor page -> save results

Quick start

cp .env.example .env
export SOCQ_API_KEY="your-api-key"

Run the complete Node.js workflow:

cd node
npm start

Run the complete Python workflow:

python3 -m pip install -r python/requirements.txt
python3 python/main.py

Both examples load payload.example.json, retry transient API responses, wait for task completion, read every cursor page, and save a paginated public Reddit comment dataset with thread and source-post references to output/results.json.

Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories, screenshots, fixtures, or logs.

Request

POST https://api.socq.ai/v1/reddit/comments
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json
{
  "urls": [
    "https://www.reddit.com/r/example/comments/abc123/example_post/"
  ]
}

The submit response contains data.task_id. Poll the task endpoint until data.status becomes succeeded or failed, then continue with data.results.next_cursor while data.results.has_more is true.

Complete workflow example

The Node.js and Python programs implement the production-shaped happy path:

  1. Load and validate configuration.
  2. Submit the endpoint-specific payload.
  3. Retry rate-pressure and transient server responses with bounded backoff.
  4. Poll the asynchronous task with a ten-minute application timeout.
  5. Stop cleanly on a failed task and surface the public error message.
  6. Read all cursor pages instead of silently returning only the first page.
  7. Write a stable JSON artifact containing task metadata and normalized records.

Use the synthetic files in fixtures/ for tests and documentation. They do not contain customer, account, or production data.

Production notes

See docs/production-notes.md for validation, retry, timeout, pagination, deduplication, logging, and endpoint-specific guidance.

Responsible use and platform scope

  • Use only publicly accessible Reddit posts, comments, subreddits, search results, and fields supported by the selected endpoint.
  • Do not use the examples to access private communities, restricted content, deleted content, login-only surfaces, or authentication controls.
  • SocQ is not an official API of the represented social platform and is not affiliated with or endorsed by that platform.
  • Before production use, assess the laws, platform terms, privacy obligations, and retention requirements that apply to your organization and use case.
  • Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
  • Platform names and trademarks belong to their respective owners.

This section describes the public-data boundary; it is not legal advice or a guarantee that every use case is permitted in every jurisdiction.

Repository contents

Path Purpose
curl/request.md Copy-paste submit, poll, and pagination requests
node/index.mjs Complete Node.js workflow
python/main.py Complete Python workflow
payload.example.json Safe endpoint-specific request body
fixtures/ Synthetic submit and task response shapes
docs/production-notes.md Production integration guidance