Fetch a thread

Fetch one Reddit thread — the post plus its nested comment tree. Long threads collapse deep comments behind "load more comments" pointers; you can expand them by requesting more pages.

GET /v1/reddit/thread/{post_id}

Path parameter

Parameter	Description
post_id	The post id (1n8xyz), a t3_ fullname, a permalink, or a full URL. See identifiers.

Query parameters

Parameter	Type	Default	Description
sort	string	confidence	Comment sort: confidence (best), top, new, controversial, old, qa.
comment_limit	integer	500	Comments to request for the base thread page. Maximum 500.
max_pages	integer	1	Total pages to fetch. The base thread is 1 page; each additional page expands one batch of collapsed comments. Maximum 100.

Comment pagination

The base thread already returns the top slice of comments. Increase max_pages to expand collapsed "load more comments" nodes — each extra page pulls one more batch (up to 100 nodes) and re-attaches them into the tree. Set max_pages=1 for a cheap, shallow read; raise it to walk deep threads.

Example

curl "$LISTENX_BASE/v1/reddit/thread/1n8xyz?max_pages=5" \
  -H "X-API-Key: $LISTENX_KEY"

Response

{
  "post": {
    "id": "1n8xyz",
    "fullname": "t3_1n8xyz",
    "type": "text",
    "title": "Best health insurance for expats?",
    "selftext": "Just moved to Zurich and…",
    "permalink": "https://www.reddit.com/r/Switzerland/comments/1n8xyz/best_health_insurance_for_expats/",
    "subreddit": "Switzerland",
    "author": "expat_zrh",
    "created_at": "2025-09-10T08:14:03+00:00",
    "engagement": {
      "score": 128,
      "upvote_ratio": 0.94,
      "num_comments": 73,
      "total_awards_received": 1
    }
  },
  "sort": "confidence",
  "pages_requested": 5,
  "pages_fetched": 5,
  "comment_count": 214,
  "has_more_comments": false,
  "comments": [
    {
      "id": "caa111",
      "fullname": "t1_caa111",
      "author": "helpful_local",
      "author_fullname": "t2_def456",
      "body": "Assura and Helsana are the usual starting points…",
      "permalink": "https://www.reddit.com/r/Switzerland/comments/1n8xyz/_/caa111/",
      "parent_id": "t3_1n8xyz",
      "depth": 0,
      "created_at": "2025-09-10T08:41:22+00:00",
      "edited_at": null,
      "is_submitter": false,
      "stickied": false,
      "distinguished": null,
      "engagement": {
        "score": 54,
        "ups": 54,
        "downs": 0,
        "controversiality": 0,
        "total_awards_received": 0
      },
      "replies": [
        {
          "id": "cbb222",
          "fullname": "t1_cbb222",
          "author": "expat_zrh",
          "body": "Thanks! Is Assura really that cheap?",
          "parent_id": "t1_caa111",
          "depth": 1,
          "is_submitter": true,
          "engagement": { "score": 8 },
          "replies": [],
          "more_replies": null
        }
      ],
      "more_replies": null
    }
  ],
  "billing": {
    "endpoint": "reddit.thread",
    "units": 5,
    "unit_price": "0.020000",
    "amount": "0.100000",
    "balance_after": "97.240000",
    "request_id": "…"
  }
}

Fields

Field	Description
post	The post record (same shape as a search result).
sort	The comment sort used.
pages_requested	The max_pages you asked for.
pages_fetched	Pages actually fetched — base thread + expansions (also the billed unit count).
comment_count	Total comment nodes returned, including nested replies.
has_more_comments	true if collapsed comments remain unexpanded (raise max_pages to pull more).
comments[]	The comment tree; each node's replies[] is the same shape, recursively.

Comment node

Field	Description
id / fullname	Comment id (caa111) and Reddit fullname (t1_caa111).
author	Username, or null if deleted.
body	Comment text (Markdown source).
parent_id	Fullname of the parent (t3_… for top-level, t1_… for a reply).
depth	Nesting depth (0 = top-level).
is_submitter	true if the commenter is the original poster (OP).
replies[]	Nested child comments (same shape).
more_replies	{ count, children[] } when deeper replies exist beyond what was fetched — otherwise null.

Billing

Billed per page fetched — units = pages_fetched, minimum 1. The base thread is one page; each max_pages step that expands collapsed comments adds a page, so cost adds up with comment pagination. A max_pages=5 fetch costs up to 5 units (fewer if the thread has no more comments to expand). See Billing.

Errors

HTTP	code	Meaning
400	invalid_post_id	Not a valid post id / URL.
404	thread_not_found	Private, removed, or nonexistent.
429	upstream_rate_limited	Transient upstream block — retry with backoff.