# Fetch up to 100 posts and comments, and 100 communities, in one call

`POST /v1/reddit/lookup`

Current state of items you already know about: fresh scores and comment counts, whether a
post was removed (`removedByCategory`) or a comment deleted (`[deleted]` body), and
community metadata — in one request instead of one per item. Accepts the links people
actually paste.

Items Reddit did not return (deleted, nonexistent, or not publicly readable) are listed in
`meta.missing` as `t3_<id>`, `t1_<id>`, or `r/<name>`. Results are not filtered for NSFW:
you named these items. Billed per item returned.

**Price:** 1 credit per call, plus 3 credits per Reddit post and 3 credits per Reddit comment and 1 credit per subreddit returned. Failed and refused calls cost nothing.

**Rate limit:** Counts as 2 requests against your per-minute rate limit.

**MCP tool:** `lookup_reddit`, on every [MCP](/mcp) connection.

Requires an API key, sent as `Authorization: Bearer <key>`.

## Request

```bash
curl --request POST \
  --url https://api.weirapp.io/v1/reddit/lookup \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

### Body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `posts` | array of string | no | Posts, as ids (`1vdo8we`), `t3_` fullnames, post URLs, or `redd.it` links. Share links (`/s/...`) carry no id and are refused. |
| `comments` | array of string | no | Comments, as ids, `t1_` fullnames, or comment permalinks. |
| `subreddits` | array of string | no | Communities, by name, `r/name`, or community URL. |

## Response

The items that exist and are publicly readable, in Reddit's own field names.

### `200`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | object | yes |  |
| `data.posts` | array of object | yes |  |
| `data.posts[].id` | string | yes | Reddit's base-36 post id, without the `t3_` prefix. |
| `data.posts[].subreddit` | string | yes | Community name without the `r/` prefix. |
| `data.posts[].title` | string | yes |  |
| `data.posts[].selftext` | string | yes | Body text. Empty for a link post. |
| `data.posts[].author` | string | yes | Username without the `u/` prefix. `[deleted]` if removed. |
| `data.posts[].permalink` | string | yes | Path on reddit.com, beginning with a slash. |
| `data.posts[].url` | string | yes | Absolute URL to the post. |
| `data.posts[].score` | integer | yes | Upvotes minus downvotes. Can be negative, and is fuzzed by Reddit. |
| `data.posts[].upvoteRatio` | number | yes | Fraction of votes that were upvotes. · 0–1 |
| `data.posts[].numComments` | integer | yes | min 0 |
| `data.posts[].over18` | boolean | yes | Marked NSFW by the author or a moderator. |
| `data.posts[].createdUtc` | number | yes | Creation time in epoch seconds, as Reddit reports it. |
| `data.posts[].createdAt` | string (date-time) | yes | The same instant as `createdUtc`, in ISO 8601. |
| `data.posts[].domain` | string | yes | `self.<subreddit>` for a text post; otherwise the host the post links to. |
| `data.posts[].isSelf` | boolean | yes | A text post rather than a link. |
| `data.posts[].urlOverriddenByDest` | string or null | yes | Where a link post points. Null for a text post. |
| `data.posts[].linkFlairText` | string or null | yes | The post's flair, such as `Question` or `Hiring`. Null when it has none. |
| `data.posts[].authorFlairText` | string or null | yes | The author's flair in this community. |
| `data.posts[].distinguished` | string or null | yes | `moderator` or `admin` when posted in an official capacity; otherwise null. |
| `data.posts[].stickied` | boolean | yes | Pinned to the top of the community. |
| `data.posts[].locked` | boolean | yes | New comments are disabled. |
| `data.posts[].archived` | boolean | yes | Past Reddit's archive age: no new comments or votes. |
| `data.posts[].spoiler` | boolean | yes |  |
| `data.posts[].edited` | number or null | yes | When the post was last edited, in epoch seconds. Null if it never was. |
| `data.posts[].numCrossposts` | integer | yes | min 0 |
| `data.posts[].crosspostParent` | string or null | yes | The original post's id, without `t3_`, when this post is a crosspost. |
| `data.posts[].removedByCategory` | string or null | yes | Why the post was removed: `moderator`, `deleted`, `author`, `automod_filtered`, `reddit`, and so on. Null while it is visible. |
| `data.posts[].subredditSubscribers` | integer | yes | Members of the community at the time the post was read. · min 0 |
| `data.posts[].postHint` | string or null | yes | What the post holds when Reddit says: `image`, `link`, `hosted:video`, `self`. |
| `data.posts[].isVideo` | boolean | yes |  |
| `data.comments` | array of object | yes |  |
| `data.comments[].id` | string | yes | Reddit's base-36 comment id, without the `t1_` prefix. |
| `data.comments[].postId` | string | yes | The post this comment belongs to, without `t3_`. |
| `data.comments[].parentId` | string | yes | The comment or post this replies to. |
| `data.comments[].author` | string | yes | Username without the `u/` prefix. `[deleted]` if removed. |
| `data.comments[].body` | string | yes | Markdown. `[removed]` or `[deleted]` once taken down. |
| `data.comments[].score` | integer | yes |  |
| `data.comments[].permalink` | string | yes | Absolute URL of the comment. |
| `data.comments[].createdUtc` | number | yes |  |
| `data.comments[].createdAt` | string (date-time) | yes |  |
| `data.comments[].subreddit` | string | yes | Community name without the `r/` prefix. |
| `data.comments[].isSubmitter` | boolean | yes | The commenter is the post's author (OP). |
| `data.comments[].edited` | number or null | yes | When the comment was last edited, in epoch seconds. Null if it never was. |
| `data.comments[].distinguished` | string or null | yes | `moderator` or `admin` when posted in an official capacity; otherwise null. |
| `data.comments[].stickied` | boolean | yes | Pinned under the post by a moderator. |
| `data.comments[].scoreHidden` | boolean | yes | Reddit is hiding this comment's score for now; `score` means nothing while true. |
| `data.comments[].linkTitle` | string | yes | Title of the post the comment belongs to. |
| `data.comments[].linkAuthor` | string | yes | Author of that post. |
| `data.comments[].linkPermalink` | string | yes | Absolute URL of that post. |
| `data.comments[].numComments` | integer | yes | Comments on that post. · min 0 |
| `data.comments[].over18` | boolean | yes | That post is marked NSFW. |
| `data.subreddits` | array of object | yes |  |
| `data.subreddits[].id` | string | yes | Reddit's fullname for the community, `t5_` included. |
| `data.subreddits[].name` | string | yes | Community name without the `r/` prefix. |
| `data.subreddits[].title` | string | yes |  |
| `data.subreddits[].description` | string or null | yes | The short public description. Null if unset. |
| `data.subreddits[].url` | string | yes |  |
| `data.subreddits[].subscribers` | integer | yes | min 0 |
| `data.subreddits[].over18` | boolean | yes | The whole community is marked NSFW. |
| `data.subreddits[].createdUtc` | number | yes |  |
| `data.subreddits[].createdAt` | string (date-time) | yes |  |
| `data.subreddits[].subredditType` | string | yes | `public`, `restricted`, `private`, `archived`, `gold_restricted`, or `user`. |
| `data.subreddits[].submissionType` | string or null | yes | What may be posted: `any`, `link`, or `self`. |
| `data.subreddits[].lang` | string or null | yes | The community's declared language, such as `en`. |
| `data.subreddits[].quarantine` | boolean | yes | Quarantined by Reddit: hidden from search and listings. |
| `data.subreddits[].communityIcon` | string or null | yes | URL of the community icon. Null if unset. |
| `data.subreddits[].bannerImg` | string or null | yes | URL of the banner image. Null if unset. |
| `meta` | object | yes |  |
| `meta.requestId` | string | yes |  |
| `meta.missing` | array of string | yes | What was asked for and not returned: `t3_<id>`, `t1_<id>`, `r/<name>`. |

## Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request failed validation. | The request was malformed. The `details` object names the field. |
| `401` | The API key is missing, malformed, expired, or revoked. | The key is missing, malformed, revoked, or expired. |
| `402` | The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes. | Out of credits. **Never retry.** Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will. |
| `403` | The API key does not carry the scope this route requires. | The key is valid but lacks the scope this operation needs. |
| `404` | The requested resource does not exist. | No such resource, or it is not public. |
| `429` | The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again. | Rate limited. Retryable: wait for `Retry-After`, then try again. |
| `500` | An unexpected error occurred. | Something failed on our side. Retryable with backoff. |
| `503` | The source is temporarily unavailable. The request is safe to retry. | A source was unreachable. Retryable with backoff. |