# Reddit posts API

Platform: Reddit.

Call `GET /v1/reddit/subreddits/{name}/posts` with the subreddit name, without the `r/`. Each request returns one page of posts and a cursor for the next page.

You do not need a Reddit OAuth client or data access approval.

## GET /v1/reddit/subreddits/{name}/posts?sort=hot

```bash
curl "https://api.openhandle.dev/v1/reddit/subreddits/synthetic/posts?sort=hot" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"
```

```ts
import { OpenHandle } from '@openhandle/sdk';

const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_API_KEY! });
const page = await openhandle.reddit.subreddit('synthetic').posts.list({ sort: 'hot' });

for (const post of page.data) console.log(post.metrics.score, post.title);
```

200 OK:

```json
{
  "platform": "reddit",
  "resource": "post",
  "capturedAt": "2026-09-18T11:04:19Z",
  "source": "live",
  "data": [
    {
      "id": "t3_reddit1",
      "title": "Synthetic Reddit post",
      "community": {
        "id": "t5_reddit1",
        "handle": "synthetic",
        "displayHandle": "r/synthetic"
      },
      "createdAt": "2026-08-09T15:30:00Z",
      "metrics": { "score": 0, "upvoteRatio": 0.5, "comments": 0, "crossposts": 0 }
    }
  ],
  "meta": { "cursors": { "next": "b3BhcXVlLWN1cnNvcg" } }
}
```

Trimmed to one post and the fields most apps need. The example is a Test subreddit, so you can run it on a free Test key.

## What you get

- **Posts.** Each post has `id`, `title`, `createdAt`, and the subreddit in `community`.
- **Counts.** Score, upvote ratio, comments, and crossposts sit in `metrics`.
- **Sort.** Use `sort` with `hot`, `new`, `top`, `rising`, or `controversial`, as on Reddit.
- **More posts.** Search posts with `GET /v1/reddit/search/posts`. Read one user’s posts with `GET /v1/reddit/profiles/{identifier}/posts`.

## Price

- **Per request.** $0.0025 per live request. $0.002 per request after 100,000 requests in a month. One page of results is one request.
- **Older data costs less.** Set `freshness` to say how old the data may be. Data up to 24 hours old: $0.0005. Data up to 7 days old: $0.0001. Data up to 30 days old: free.
- **Failed means free.** Errors and invalid requests are never billed. You pay for answers, and a confirmed not-found is an answer.
- **Free to start.** Every new workspace starts with 100 free live requests, no card needed. Test keys are never charged.

## When this does not work

These answers are definitive. Store them, do not retry them.

| Situation | Status | Code |
|---|---|---|
| The subreddit is private, quarantined, or banned | 403 | `PROFILE_PRIVATE` |
| The subreddit never existed | 404 | `PROFILE_NOT_FOUND` |
| The cursor came from another sort or subreddit | 400 | `CURSOR_MISMATCH` |

```json
{
  "error": {
    "code": "PROFILE_PRIVATE",
    "message": "This profile is private.",
    "requestId": "req_01j8…",
    "retryable": false
  }
}
```

A cursor is bound to its subreddit and sort. Change either one and start without a cursor.

## Related

- [Reddit API](https://openhandle.dev/apis/reddit): Every Reddit endpoint with examples.
- [List subreddit posts](https://openhandle.dev/docs/api-reference/reddit-subreddit-posts-list): The endpoint reference with every parameter and SDK.
- [How do I get Reddit data without an API key?](https://openhandle.dev/questions/how-do-i-get-reddit-data-without-an-api-key): Why the .json trick stopped working and what to use now.