> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Reddit

> What a keyword captures on Reddit, and what arrives in each event.

## Coverage

A search on Reddit polls **posts**, **comments**, or both: one mode per search, chosen with `types`. The criteria below are Reddit's own, so they go in the search's `overrides.filters` on the keyword (see [Keywords](/keywords#create)).

| Criterion | Values | Default |
| - | - | - |
| `types` | `posts`, `comments`, `all` | `posts` |
| `subreddit` | a name, or several Reddit-style (`webdev+reactjs`) | none |
| `includeNsfw` | boolean | `true` |

In `posts` mode a search runs **post search**, or lists a **subreddit's** newest posts when it carries no term. Post search accepts Reddit's own query syntax in `query` (`title:keyword`, `author:username`, `flair:text`, `self:yes`, `url:domain.com`) and `subreddit` scopes it. A search can carry several terms at once, OR'd into one upstream request at one tick's cost.

Interval: **60 to 86400** seconds. At most **20** active Reddit searches per Account. Each tick costs **4 credits** in `posts` and `comments`, and **8 credits** in `all`, which reads two listings a tick.

## Comments

Most of what people say about a product on Reddit, they say in a comment, not in a submission's title. `types: "comments"` reads comments instead of posts: a subreddit's newest comments when you name one, or the comments a term finds site-wide when you do not.

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "figma on Reddit",
    "refreshIntervalSeconds": 300,
    "globalCriteria": { "market": "global", "query": "figma" },
    "sources": [
      {
        "source": "reddit",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": { "filters": { "types": "comments", "subreddit": "webdev+reactjs" } }
          }
        ]
      }
    ],
    "webhookUrl": "https://example.com/hooks/nephia"
  }'
```

Four things to know about this mode.

**A subreddit or a term is required.** With a subreddit, the search reads that subreddit's newest comments. Several are allowed in Reddit's own syntax, `webdev+reactjs+nextjs`, and cost one listing, one tick, one credit charge, exactly like a single one. Without a subreddit, the search reads comments **site-wide** by the term, newest first: the same search the "Comments" tab of Reddit's own search bar runs. Neither alone is refused; both missing is, because there is no useful "every comment on Reddit".

**On a subreddit, a term filters; it does not search.** A comment listing takes no query, so `query` (or `terms`) is matched **on our side**, over the page that came back, and it is applied whatever `match` mode the search carries, because nothing upstream did any searching. A term nothing said recently therefore finds nothing recently. Leave `query` out and the search reports every new comment in the subreddit.

**Site-wide, the term searches, and is still matched on our side.** Reddit's comment search matches loosely (a search for `stalkr` also returns `stalker`), so the term is matched again over what came back, whatever `match` mode the search carries. Set `match: "word"` to tighten it further.

**Each tick reads one page.** On a subreddit that is 100 comments, Reddit's maximum; site-wide it is the short page the search serves, about eight. If more comments arrive between two ticks than a page holds, the ones in the gap are missed: neither route has a window to reach back into. When a tick can prove it fell behind (a full page that shares nothing with the previous one), the keyword says so in its activity, readable through `GET /v1/keywords/{id}/activity`. Lower the Source's `refreshIntervalSeconds` when you see it: an active subreddit or a busy term wants 60–120 seconds, a quiet one is fine at 900.

**History is shallow on a subreddit, deeper site-wide.** A subreddit listing stops at about a thousand items, so it reaches back hours rather than weeks on a busy subreddit. The site-wide search pages back as far as the term goes. See [Day-one backfill](/keywords#backfill) for what `backfill: true` reads when the keyword is created.

### NSFW

NSFW posts are **included by default**. Set `includeNsfw: false` on the search to filter them out. The `isNsfw` field is always present on post objects.

## Posts and comments

`types: "all"` reads both halves of a subreddit in a single tick: its newest posts **and** its newest comments. One search, one webhook, one line in the sidebar, instead of two of each on the same subject.

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "figma on Reddit",
    "refreshIntervalSeconds": 300,
    "globalCriteria": { "market": "global", "query": "figma" },
    "sources": [
      {
        "source": "reddit",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": { "filters": { "types": "all", "subreddit": "webdev+reactjs" } }
          }
        ]
      }
    ],
    "webhookUrl": "https://example.com/hooks/nephia"
  }'
```

**It costs 8 credits a tick.** Two listings means two requests, and the tariff follows the requests: `all` is billed at twice the rate of either half. Two separate searches would cost the same 8: this mode buys you one configuration and one feed, not a discount.

**A subreddit or a term is required**, for the same reason as in `comments`: the comments half is a subreddit listing when a subreddit is named, and the site-wide comment search by the term otherwise. The multi-subreddit syntax (`webdev+reactjs`) applies to both halves.

**Each half keeps its own event type.** A submission arrives as `post.created`, a comment as `reddit_comment.created`, exactly what two separate searches would have delivered. `all` is a mode of polling, not a third kind of content.

**The term is asymmetric, and worth understanding.** On the posts half, `query` is sent to Reddit and matched by Reddit's own index, with its stemming and its ranking. On the comments half there is nothing to send it to, so it is matched **on our side** over the page that came back. One `match` mode, two matching semantics. Set `match: "word"` to tighten both.

**A first scan reads both halves.** A keyword created with `backfill: true` reads each listing, and the scan is billed for the requests it actually makes: 8 when both halves are read, like any other tick in this mode.

## What an event carries

A post is delivered as a `post.created` event with the full enriched post: title, body, author, subreddit, score and the link it submitted. A comment is delivered as **`reddit_comment.created`**, in the same `post` object, with `kind: "comment"`:

| Field | On a comment |
| - | - |
| `kind` | `"comment"`; absent means a post |
| `id`, `fullname` | the `t1_…` fullname |
| `parentPostId` | the bare id of the submission it sits under |
| `title` | the **parent submission's** title |
| `selftext`, `selftextHtml` | the comment's own body |
| `permalink`, `url` | the comment's own link |
| `numComments`, `awards`, `previewImages` | empty: a comment carries none |

The first tick of a search establishes a silent baseline and emits nothing. `webhookUrl` is optional: without it the keyword still records every match, readable through `GET /v1/keywords/{id}/events` in the same shape. See [Webhooks](/webhooks#replay).

### Ids

Post ids are normalised to a bare base36 `id` plus a `fullname` (`t3_…`), whichever form Reddit used. **A comment's `id` is its full `t1_…` name**, prefix included: Reddit numbers comments and posts on separate sequences, so a bare comment id can collide with a post id, and the prefix is what keeps two different items from counting as one.

## Limits

A post removed or deleted after a keyword captured it keeps its recorded event: the feed is what we saw, at the time we saw it. A private or banned subreddit simply stops producing matches; the keyword reports the failure in its activity rather than silently going quiet, readable through `GET /v1/keywords/{id}/activity`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.