# Reddit API for agents

> API for Agents · https://apiforagents.dev/platforms/reddit · HTML twin: https://apiforagents.dev/platforms/reddit

Posts, comments, subreddits and search from Reddit, with scores and permalinks on every row.

Endpoint: `POST https://apiforagents.dev/v1/reddit`. One op per call. Quote first with `"estimateOnly": true`.

## Prices (USD per record, pay as you go)

| Record | Per record |
|---|---|
| comments | $0.0045 |
| posts | $0.0045 |

## Operations

### posts

One user's recent submissions. Score, comment count, upvote ratio and the kind of each post.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subject | yes | string (≤400 chars) | One u/username or profile URL. |
| limit | no | integer (1-50) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| postId | string |
| author | string |
| subreddit | string |
| title | string |
| body | string |
| kind | string |
| flair | string |
| isNsfw | boolean |
| permalink | string |
| externalUrl | string |
| mediaUrl | string |
| thumbnailUrl | string |
| postedAt | string |
| editedAt | string |
| score | integer |
| upvoteRatio | number |
| commentsCount | integer |
| subredditSubscribers | integer |
| fullname | string |
| gallery | list of string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/reddit \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"posts","subject":"u/spez","limit":25}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "author": "u/quietbuilder",
    "subreddit": "r/startups",
    "title": "What we learned pricing our first B2B product",
    "kind": "text",
    "score": 1240,
    "upvoteRatio": 0.96,
    "commentsCount": 318,
    "postedAt": "2026-10-14T10:00:00Z",
    "postId": "226223522",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/what-we-learned-pricing-our-first-b2b-pr-1000",
    "externalUrl": "https://www.reddit.com/what-we-learned-pricing-our-first-b2b-pr-1000",
    "mediaUrl": "https://www.reddit.com/what-we-learned-pricing-our-first-b2b-pr-1000",
    "thumbnailUrl": "https://img.reddit.com/what-we-learned-pricing-our-first-b2b-pr.jpg",
    "editedAt": "2026-10-09",
    "details": {}
  },
  {
    "author": "u/quietbuilder",
    "subreddit": "r/SaaS",
    "title": "Our churn halved after one onboarding change",
    "kind": "text",
    "score": 860,
    "upvoteRatio": 0.94,
    "commentsCount": 144,
    "postedAt": "2026-10-02T16:30:00Z",
    "postId": "220858165",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/our-churn-halved-after-one-onboarding-ch-1001",
    "externalUrl": "https://www.reddit.com/our-churn-halved-after-one-onboarding-ch-1001",
    "mediaUrl": "https://www.reddit.com/our-churn-halved-after-one-onboarding-ch-1001",
    "thumbnailUrl": "https://img.reddit.com/our-churn-halved-after-one-onboarding-ch.jpg",
    "editedAt": "2026-10-12",
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=reddit&op=posts (sign in first).

### subreddit

A subreddit's listing under one sort. `postedWithin` applies to `top` only. Reddit ignores it for every other sort.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subject | yes | string (≤400 chars) | One r/name or subreddit URL. |
| sort | no | enum |  Values: hot, newest, top, rising. |
| postedWithin | no | enum |  Values: 1h, 1d, 7d, 30d, 1y, any. |
| limit | no | integer (1-50) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| postId | string |
| author | string |
| subreddit | string |
| title | string |
| body | string |
| kind | string |
| flair | string |
| isNsfw | boolean |
| permalink | string |
| externalUrl | string |
| mediaUrl | string |
| thumbnailUrl | string |
| postedAt | string |
| editedAt | string |
| score | integer |
| upvoteRatio | number |
| commentsCount | integer |
| subredditSubscribers | integer |
| fullname | string |
| gallery | list of string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/reddit \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"subreddit","subject":"r/technology","sort":"top","postedWithin":"7d","limit":25}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "author": "u/brew_nerd",
    "subreddit": "r/coffee",
    "title": "Best grinder under $200 in 2026?",
    "kind": "text",
    "flair": "Gear",
    "score": 286,
    "upvoteRatio": 0.97,
    "commentsCount": 241,
    "postedAt": "2026-10-11T09:00:00Z",
    "subredditSubscribers": 2410000,
    "postId": "2117003186",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/best-grinder-under-200-in-2026-1000",
    "externalUrl": "https://www.reddit.com/best-grinder-under-200-in-2026-1000",
    "mediaUrl": "https://www.reddit.com/best-grinder-under-200-in-2026-1000",
    "thumbnailUrl": "https://img.reddit.com/best-grinder-under-200-in-2026.jpg",
    "editedAt": "2026-10-09",
    "details": {}
  },
  {
    "author": "u/latteart_lou",
    "subreddit": "r/coffee",
    "title": "My first decent heart after 3 months!",
    "kind": "image",
    "flair": "Latte art",
    "score": 1920,
    "upvoteRatio": 0.98,
    "commentsCount": 96,
    "postedAt": "2026-10-10T18:40:00Z",
    "subredditSubscribers": 2410000,
    "postId": "4131271503",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/my-first-decent-heart-after-3-months-1001",
    "externalUrl": "https://www.reddit.com/my-first-decent-heart-after-3-months-1001",
    "mediaUrl": "https://www.reddit.com/my-first-decent-heart-after-3-months-1001",
    "thumbnailUrl": "https://img.reddit.com/my-first-decent-heart-after-3-months.jpg",
    "editedAt": "2026-10-11",
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=reddit&op=subreddit (sign in first).

### comments

Top comments on up to ten POSTS, by permalink or bare post id. Commenters are free text. Not corpus members.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subjects | yes | list of string (1-10 items) | Post permalinks or bare post ids. |
| limit | no | integer (1-100) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| commentId | string |
| parentId | string |
| author | string |
| body | string |
| score | integer |
| depth | integer |
| postedAt | string |
| isOp | boolean |
| permalink | string |
| parentFullname | string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/reddit \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"comments","subjects":["https://www.reddit.com/r/technology/comments/<post-id>/"],"limit":50}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "author": "u/kai_dev",
    "body": "Charge more than feels comfortable. Then talk to every churned user.",
    "score": 412,
    "depth": 0,
    "isOp": false,
    "postedAt": "2026-10-14T10:30:00Z",
    "commentId": "2387243326",
    "parentId": "4795852",
    "permalink": "https://www.reddit.com/u-kai-dev-1000",
    "details": {}
  },
  {
    "author": "u/quietbuilder",
    "body": "This. We doubled price and lost only 4% of signups.",
    "score": 128,
    "depth": 1,
    "isOp": true,
    "postedAt": "2026-10-14T10:52:00Z",
    "commentId": "2972310197",
    "parentId": "2461267070",
    "permalink": "https://www.reddit.com/u-quietbuilder-1001",
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=reddit&op=comments (sign in first).

### search

Posts across all of Reddit matching a keyword. What Reddit is saying about something. `postedWithin` applies to `top` only.

| Field | Required | Type | Meaning |
|---|---|---|---|
| query | yes | string (≤300 chars) |  |
| sort | no | enum |  Values: relevance, hot, top, newest, most_commented. |
| postedWithin | no | enum |  Values: 1h, 1d, 7d, 30d, 1y, any. |
| limit | no | integer (1-50) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| postId | string |
| author | string |
| subreddit | string |
| title | string |
| body | string |
| kind | string |
| flair | string |
| isNsfw | boolean |
| permalink | string |
| externalUrl | string |
| mediaUrl | string |
| thumbnailUrl | string |
| postedAt | string |
| editedAt | string |
| score | integer |
| upvoteRatio | number |
| commentsCount | integer |
| subredditSubscribers | integer |
| fullname | string |
| gallery | list of string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/reddit \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"search","query":"electric cars","sort":"top","postedWithin":"30d","limit":25}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "author": "u/dataops_dan",
    "subreddit": "r/dataengineering",
    "title": "dbt vs plain SQL for a 3-person team?",
    "kind": "text",
    "score": 412,
    "upvoteRatio": 0.93,
    "commentsCount": 187,
    "postedAt": "2026-10-12T14:00:00Z",
    "postId": "482552129",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/dbt-vs-plain-sql-for-a-3-person-team-1000",
    "externalUrl": "https://www.reddit.com/dbt-vs-plain-sql-for-a-3-person-team-1000",
    "mediaUrl": "https://www.reddit.com/dbt-vs-plain-sql-for-a-3-person-team-1000",
    "thumbnailUrl": "https://img.reddit.com/dbt-vs-plain-sql-for-a-3-person-team.jpg",
    "editedAt": "2026-10-14",
    "details": {}
  },
  {
    "author": "u/sofia_codes",
    "subreddit": "r/analytics",
    "title": "Is dbt worth it for small data?",
    "kind": "text",
    "score": 198,
    "upvoteRatio": 0.9,
    "commentsCount": 76,
    "postedAt": "2026-10-08T11:20:00Z",
    "postId": "3942850405",
    "isNsfw": false,
    "permalink": "https://www.reddit.com/is-dbt-worth-it-for-small-data-1001",
    "externalUrl": "https://www.reddit.com/is-dbt-worth-it-for-small-data-1001",
    "mediaUrl": "https://www.reddit.com/is-dbt-worth-it-for-small-data-1001",
    "thumbnailUrl": "https://img.reddit.com/is-dbt-worth-it-for-small-data.jpg",
    "editedAt": "2026-10-07",
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=reddit&op=search (sign in first).

### history (free)

The stored score / comment-count series of up to ten posts. Free, reads only what captures already wrote.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subjects | yes | list of string (1-10 items) | Post permalinks or bare post ids. |
| metric | no | enum |  Values: score, comments_count. |
| days | no | integer (1-730) |  |

Request shape:

```json
{
  "op": "history",
  "subjects": [
    "example"
  ]
}
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=reddit&op=history (sign in first).

## Notes for the agent

Measured Reddit data, one operation per call. The POST is the entity: score, upvote ratio, comment count, kind and permalink on every row. There is no profile card. Reddit publishes none we can measure. ops: posts (one user's recent submissions. U/name or a profile URL), subreddit (a subreddit's listing under one sort: hot | newest | top | rising; `postedWithin` applies to top only), comments (top comments on up to ten posts, by permalink or bare id), search (posts across Reddit matching a keyword. What Reddit is saying about something; sorts relevance | hot | top | newest | most_commented), history (stored score / comment-count series of posts already held, free). Ops are independent. Issue several as PARALLEL tool calls. Fresh fetches are charged per record; your own answer is free while fresh.