# Community

Schemas

Public communities people join and post in (subreddits, Facebook groups), with their description, rules, privacy and member count.

## Endpoints

4 endpoints return communities on Facebook, Reddit and X.

- [GETFacebook Group API`/v1/facebook/group`](https://socialtap.dev/docs/reference/facebook/group/index.md)
- [GETReddit Subreddit Search API`/v1/reddit/search_subreddits`](https://socialtap.dev/docs/reference/reddit/search_subreddits/index.md)
- [GETReddit Subreddit API`/v1/reddit/subreddit`](https://socialtap.dev/docs/reference/reddit/subreddit/index.md)
- [GETX (Twitter) Community API`/v1/x/community`](https://socialtap.dev/docs/reference/x/community/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (reddit, facebook, …). |
| `id` | `string` | Platform-native community ID (string): Reddit's subreddit ID with its t5_ prefix, Facebook's numeric group ID. |
| `name` | `string` or `null` | The name its links use, without a prefix (golang for r/golang; a Facebook group's vanity name); null when it has none (a Facebook group known only by its number). |
| `title` | `string` or `null` | The community's title as its page shows it ("The Go Programming Language"; what Facebook calls a group's name); null when it has none. |
| `description` | `string` or `null` | Its short description as plain text; null when it has none. |
| `url` | `string` (uri) | Canonical community URL (https://www.reddit.com/r/golang/, https://www.facebook.com/groups/\<id>/). |
| `avatar_url` | `string` (uri) or `null` | The community's icon or picture; null when it has none. Platform CDN URLs can expire. |
| `banner_url` | `string` (uri) or `null` | Header or cover image URL; null when it has none. |
| `privacy` | `string` or `null` | public: anyone can see its posts and any member can post; restricted: anyone can see its posts, only approved members can post; private: only members can see its posts (a private community answers private_or_unavailable unless its page shows these fields logged out). New values may be added; treat unknown values as restricted.<br>One of `public`, `restricted`, `private` |
| `is_nsfw` | `boolean` or `null` | Marked adult (NSFW) by the platform; null where the platform has no such mark. |
| `categories` | `string[]` | Topics or categories the platform files it under, as shown (not normalized); \[\] when none. |
| `rules` | `object[]` | Its published rules, in the platform's order; \[\] when it has none (listed in unknown_fields when the source cannot see them). |
| `rules[].title` | `string` | The rule's short title (Reddit short_name, Facebook rule_title). |
| `rules[].description` | `string` or `null` | Its explanation as plain text; null when it has none. |
| `moderators` | `object[]` | Accounts that run it (admins and moderators) the platform shows; \[\] when none are shown (listed in unknown_fields when the source cannot see them). |
| `moderators[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `moderators[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `moderators[].display_name` | `string` or `null` | Display name shown on the profile. |
| `moderators[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `moderators[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `moderators[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `created_at` | `string` (date-time) or `null` | When it was created, RFC 3339 UTC. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.member_count` | `integer` or `null` | Members (on Reddit, subscribers) as the platform counts them. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.facebook` | `object` or `null` | A Facebook group's own fields. |
| `platform_specific.facebook.daily_post_count` | `integer` or `null` | Posts in the group in the last day, as Facebook counts them. |
| `platform_specific.facebook.monthly_post_count` | `integer` or `null` | Posts in the group in the last month, as Facebook counts them. |
| `platform_specific.facebook.weekly_new_member_count` | `integer` or `null` | Members who joined in the last week (parsed from Facebook's text). |
| `platform_specific.facebook.admin_count` | `integer` or `null` | Administrators of the group. |
| `platform_specific.facebook.admin_ids` | `string[]` | The IDs of the administrators among moderators (the rest are its moderators), as far as Facebook shows them; \[\] when none are shown (listed in unknown_fields when the source cannot see them). |
| `platform_specific.facebook.moderator_count` | `integer` or `null` | Moderators of the group (not counting its administrators). |
| `platform_specific.facebook.is_visible` | `boolean` or `null` | True when anyone can find the group in search (Facebook's Visible), false when only members can (Hidden). |
| `platform_specific.facebook.history_summary` | `string` or `null` | Facebook's summary of the group's history (created, name changes), as shown. |
| `platform_specific.facebook.owner` | `object` or `null` | The Page or account the group is shown as belonging to (Facebook's "Group by ..." on its cover); null when Facebook names none. |
| `platform_specific.facebook.owner.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.facebook.owner.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.facebook.owner.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.facebook.owner.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.facebook.owner.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.facebook.owner.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.facebook.locations` | `string[]` | The places the group's admins tie it to, as shown; \[\] when none. |
| `platform_specific.reddit` | `object` or `null` | A subreddit's own fields. |
| `platform_specific.reddit.weekly_visitor_count` | `integer` or `null` | Unique visitors in the last week, as the subreddit's page shows them. |
| `platform_specific.reddit.weekly_contribution_count` | `integer` or `null` | Posts and comments in the last week, as the subreddit's page shows them. |
| `platform_specific.reddit.member_nickname` | `string` or `null` | What the subreddit calls its members (gophers on r/golang); null when it has no nickname. |
| `platform_specific.reddit.is_quarantined` | `boolean` or `null` | True when Reddit has quarantined it (shown only after a warning). |
| `platform_specific.x` | `object` or `null` | An X Community's own fields. |
| `platform_specific.x.join_policy` | `string` or `null` | How people join: open (anyone), moderator_approval or admin_approval (a request someone approves), invite_only (by invitation). New values may be added.<br>One of `open`, `moderator_approval`, `admin_approval`, `invite_only` |
| `platform_specific.x.join_question` | `string` or `null` | The question X asks people who ask to join, as its moderators wrote it; null when it asks none. |
| `platform_specific.x.invite_policy` | `string` or `null` | Who can invite people in: members, moderators, admins or none. New values may be added.<br>One of `members`, `moderators`, `admins`, `none` |
| `platform_specific.x.creator` | `object` or `null` | The account that created it (it may have passed to another admin since). |
| `platform_specific.x.creator.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.x.creator.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.x.creator.display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.x.creator.url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.x.creator.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.x.creator.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.x.moderator_count` | `integer` or `null` | People who run it, its admin included, as X counts them. |
| `platform_specific.x.search_tags` | `string[]` | Words its moderators chose for people to find it by; \[\] when none (listed in unknown_fields when the source cannot see them). |
| `platform_specific.x.sample_members` | `object[]` | The few members X shows on the community's page: a sample chosen by X, not its member list. |
| `platform_specific.x.sample_members[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.x.sample_members[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.x.sample_members[].display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.x.sample_members[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.x.sample_members[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.x.sample_members[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("762.0K members": metrics.member_count). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, community endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/community/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)