Communities
Twitter community search API & keyword tweet results
Search posts inside one known X (Twitter) community by keyword. Export matching tweets, authors, replies, reposts, likes, media, and cursor pages for reviews.
- 200
- 400
- 401
- 402
- 424
- 429
- 502
- 503
GET
Twitter community search API & keyword tweet results
string
Filter to posts from this username. The
@ prefix is optional.string
Filter to replies directed to this username.
string
Filter to posts that mention this username.
string
Only include posts with this language code.
string
Include posts created on or after this date or timestamp.
string
Include posts up to this date or timestamp. A date is a UTC day, inclusive, so its own posts count.
string
Use
images, videos, gifs, media, links, or none.integer
Require this minimum like count.
integer
Require this minimum repost count.
integer
Require this minimum reply count.
integer
Require this minimum quote count.
integer
Require this minimum view count.
integer
Require this minimum bookmark count.
integer
Allow this maximum like count. Missing counts pass.
integer
Allow this maximum repost count. Missing counts pass.
integer
Allow this maximum reply count. Missing counts pass.
integer
Allow this maximum quote count. Missing counts pass.
boolean
When
true, only return posts from Blue-verified authors.boolean
When
true, only return posts from verified authors.string
Use
include, exclude, or only for replies.
This setting overrides includeReplies when the endpoint supports both.string
Use
include, exclude, or only for reposts.string
Match this literal phrase, including any hyphens.
string
Exclude comma-separated or whitespace-separated terms.
string
Require at least 1 comma-separated or whitespace-separated term.
string
Match these hashtags. Separate values with commas or spaces.
string
Match these cashtags. Separate values with commas or spaces.
string
Use
include, exclude, or only for quote posts.string
URL substring or domain that must appear in tweet URL entities.
string
Filter to tweets in this conversation thread.
string
Only include replies to this tweet ID.
string
Filter to quote tweets of this tweet ID.
string
Filter to retweets of this tweet ID.
string
Return Tweets whose IDs exceed this ID.
string
Return Tweets at or below this ID.
boolean
When
true, only return native reposts.string
Match Tweets from this recent window, such as
90m or 7d. Use a whole number & s, m, h or d.Filter one community by query
This endpoint requires a search expression. It filters one community. It does not return the unfiltered feed. Keep the query beside every saved row.
Use the community tweets endpoint when no keyword filter is required.
Twitter community search questions
Does this endpoint find communities to join?
No. This endpoint searches posts after you provide a numeric Community ID. It does not join Communities or change membership. To find Communities by keyword, use Find communities. To browse Communities by topic, use Popular communities. Read the official X Communities guide for current visibility and membership rules.How do I search community posts by keyword?
SendcommunityId and q. Omit queryType to use Latest. Set Top for
relevance-ranked matches.
Keep each cursor tied to the same values. Start a new search when the query
changes. Store the query beside every returned Tweet ID.
Why does Twitter community search return no results?
First, verify the Community ID, query, and read visibility. An empty match set differs from authentication, credit, dependency, rate-limit, or request errors. Use the Community Tweets API to inspect the visible, unfiltered feed. Zero matches do not prove an inactive Community.Can I find active authors in matching tweets?
Group matching posts by stable author ID. Count matches, replies, reposts, likes, quotes, and views separately. Store follower counts with collection times when returned. These measures describe captured matches. They do not prove influence, audience reach, Community membership, or total posting activity.GET /x/communities/search and GET /x/communities/tweets accept the same
community search parameters. This page documents both supported REST paths.402 insufficient_credits.
1 credit per tweet returned · All plans from $0.00012/credit
next_cursor row when has_next_page is true, then pass it back as cursor
with the same communityId, q, queryType, and pageSize.
Direct community search handoff
UseGET /x/communities/search when a monitoring job, research queue,
moderation review, social listening workflow, or agent needs matching tweets
from one known X community.
Store community_id, search_query, query_type, tweet_id, text, author_id,
author_username, author_name, author_followers, author_verified,
author_profile_picture, created_at, engagement counts, & media_urls for
each row. Keep
has_next_page & next_cursor with the export checkpoint. The next run can
then continue the same scoped search without duplicating earlier rows.
Set queryType=Latest for recent queues or backfills. Set queryType=Top for
relevance-ranked review.
Search row checkpoint
Store
community_id, search_query, query_type, page_size,
has_next_page, and next_cursor with the tweet rows.Sort mode
Use
Latest for recent collection and Top for relevance-ranked review.
Keep the same queryType when you pass a cursor.Default page
Request 1 to 100 tweets with
pageSize. The default is 20. The value
is an upper bound because filters, source results, or credits can return fewer.Saved export
Use
community_search with targetCommunityId and searchQuery when the
workflow needs a saved job with CSV, JSON, or XLSX output.Plan a community search export
Choose this route for repeatable research across one known community. Define the question before choosing the query. A narrow query returns fewer irrelevant tweet rows to review. Start each export with these values:- The numeric community ID.
- The exact search expression.
- Either
LatestorTop. - A stable page size.
- The time when collection started.
Latest for incident review, event coverage, and recent topic monitoring.
Use Top for relevance-ranked discovery. Do not combine both orders inside one
export file. Create separate exports when reviewers need both orders.
Normalize each tweet into named columns. Useful columns include tweet ID,
text, author username, creation time, likes, replies, reposts, and media URLs.
Keep the community ID and query on every row. Those columns keep context
after CSV or XLSX handoff.
Stop when has_next_page becomes false. Store the final checkpoint with the
row count. Deduplicate resumed exports by tweet ID. A worker that retries the last completed page
then adds no duplicate spreadsheet rows.
Write precise community queries
Use concrete terms that match the research question. Combine keywords with supported search operators when required. Test the first page before starting a large export. For moderation, search the specific phrase or hashtag under review. For research, separate broad themes into independent queries. For event coverage, record the chosen sort order and collection time. Avoid changingq after receiving a cursor. Start a new search. Each
cursor then belongs to one result set.
Validate a completed research file
Count unique tweet IDs after the final page. Compare that count with the written row count. Any difference means repeated rows. Check that every row carries the same community ID, query, and sort mode. Reject a mixed file before analyst handoff. Keep media URLs as arrays or separate child rows. Write a short export manifest. Include collection time, page count, unique tweet count, final cursor state, and output format. A reader can then understand the CSV or XLSX file without the original job logs. When a run stops early, label it partial. Keep the last saved cursor to resume. Do not present a partial export as the community’s complete search result.Schedule independent searches
Give every community-and-query pair its own checkpoint. Never share cursors between 2 terms. Run urgent moderation searches more frequently than broad research queries. Record the schedule beside the export manifest. If a query changes, start a new series. Compare only runs that used the same query. Use separate output names for each community. Include a short query slug and collection date. Keep the full query inside the manifest. Archive successful manifests beside their CSV, JSON, or XLSX files. Another analyst can then reproduce the search parameters without opening application logs. Version the manifest when a query changes. Do not edit earlier exports. Comparisons between research periods depend on them.Compare latest and top results without mixing datasets
RunLatest and Top as independent searches when research needs both views.
The 2 orders rank different tweets first and may return overlapping tweets.
Give each run its own manifest, cursor chain, and output file. Keep the same
community ID and query when comparing the 2 modes. Changing another input
would invalidate the comparison.
Use Latest to capture recent discussion. Record when you requested the
first page. New tweets can appear while you collect later pages.
Use Top to capture relevance-ranked discussion. Record the collection time,
but do not treat rank as a permanent score. The order can change later.
After both runs finish, join rows by tweet ID. Label every tweet as
latest_only, top_only, or both. Keep the original engagement counts from
each run when collection times differ.
Do not append one mode beneath the other without a source column. Analysts
could mistake duplicated tweets for extra community activity.
Validate each dataset before comparison:
- Every row uses the intended community ID.
- Every row stores the exact search query.
- Every cursor belongs to one sort mode.
- Each run removes duplicate tweet IDs.
- Partial runs remain labeled.
Query parameters
string
required
Numeric ID of the community whose tweets you want to search.
string
required
Search query for community tweets.
string
Sort order.
Top returns most relevant tweets, Latest returns most recent. Defaults to Latest.string
Pagination cursor from a previous response. Omit for the first page.
number
Upper bound for tweets per page. Range: 1-100. Default:
20.Which community search route?
Community search route
Use
GET /x/communities/search with communityId and q for scoped search.Equivalent scoped route
Use
GET /x/communities/tweets when your integration already uses that
path. It accepts the same communityId, q, queryType, cursor, and
pageSize shape.Known community posts
Use
GET /x/communities/{id}/tweets
for posts from one known community ID.Bulk community jobs
Use
Create extraction with
community_search with targetCommunityId and searchQuery when the
workflow needs a saved filtered export. Use community_post_extractor for
all posts from a known community.Build a live community review queue
Choose either documented path for direct, page-by-page tweet retrieval. Both paths work behind moderation screens, support consoles, and analyst dashboards. Show the active community ID, query, and sort mode above the results. Reviewers should always know why each tweet appeared. Render concrete tweet fields:- Tweet text, Tweet ID, and creation time.
- Author name, username, user ID, and verification state.
- Reply, repost, like, quote, and view counts when returned.
- Attached photo, video, or animated GIF URLs.
- A source URL for opening the original tweet.
next_cursor to the community, query, sort mode, and page size. Stop
paging when has_next_page is false. An empty page is a valid result, not a
missing community.
Keep decisions across a live moderation queue
Key the queue on the community ID, query, and sort mode. Store each decision againsttweet.id, never a row position. When a page fails, keep its rows and
cursor. Retry with the same parameters.
Latest rows change as new tweets arrive, so deduplicate them by Tweet ID.
Top ranking changes too, so record each collection time.
Build a query-specific community review batch
Save the exact query before requesting tweets. Give each batch 1 purpose. Store Tweet ID, author ID, text, creation time, engagement, and media for every match. Add the request time and cursor. Keep reviewer fields in a separate table keyed by Tweet ID. Record 1 terminal state: completed, capped, credit-bounded, or interrupted. A live search page never proves a complete community archive.Separate search matches from community feed coverage
Community search returns tweets matching one expression. It does not return every recent post. Use the community feed route for an unfiltered timeline. Keep match counts separate from total community activity. A narrow query can return zero tweets while the community remains active. A broad query can create more review work without improving relevance.Headers
string
Full account key. Sessions and OAuth also work.
string
Bearer xq_your_guest_key_here for paid_reads.Response
200 OK
object[]
Array of matching community tweets.
Tweet object fields.
string
Tweet ID.
string
Contains the complete Tweet text.
string
Classifies the Tweet when X returns a type.
string
ISO 8601 creation timestamp.
boolean
Whether this is a Note Tweet. Omitted if unavailable.
boolean
Whether the author pinned this post to their profile. Omitted if unavailable.
number
Reports the number of likes when available.
number
Reports the number of reposts when available.
number
Reports the number of replies when available.
number
Reports the number of quotes when available.
number
Reports the number of views when available.
number
Reports the number of bookmarks when available.
string
Permalink URL on X. Omitted if unavailable.
string
Reports the Tweet language code when available.
boolean
Whether the tweet is a reply. Omitted if unavailable.
string
Tweet ID being replied to. Omitted if not a reply.
string
Identifies the replied-to user when available.
string
Reports the replied-to username when available.
string
Conversation thread ID. Omitted if unavailable.
string
Client used to post the tweet. Omitted if unavailable.
number[]
Start and end offsets for rendered tweet text. Omitted if unavailable.
boolean
Whether replies are limited. Omitted if unavailable.
boolean
Whether this tweet quotes another tweet. Omitted if unavailable.
boolean
Whether this row is a retweet.
text carries the original post in full.object
Parsed entities. Omitted if unavailable.
object
Returns paid-promotion and AI-generated-media labels when available. Includes
advertising.isPaidPromotion and aiGenerated.hasAiGeneratedMedia.object
Tweet author profile. Omitted if unavailable.
Author object fields.
string
Author user ID.
string
Author X username.
string
Author display name.
number
Reports the author’s follower count when available.
boolean
Whether the author is verified. Omitted if unavailable.
string
Profile picture URL. Omitted if unavailable.
object[]
object
Embedded quoted tweet. Omitted if not a quote tweet.
object
Original retweeted tweet. Omitted if not a retweet.
boolean
Whether more results are available.
string
Cursor for the next page. Pass as the
cursor query parameter.400 Missing query
q query parameter is empty or missing.
401 Unauthenticated
Anonymous requests getWWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.
402 Payment required
Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.502 X API unavailable
429 Rate limit exceeded
Retry-After header before retrying.
424 Dependency failed
Next steps. Community Info to look up a community, or Search Tweets for general tweet search.