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
GET
Twitter community search API & keyword tweet results
string
Only include posts with this language code.
string
Use
images, videos, gifs, media, links, or none.integer
Require this minimum like count.
integer
Require this minimum reply count.
integer
Require this minimum repost count.
integer
Require this minimum view count.
string
Include posts created on or after this date or timestamp.
string
Include posts before this date or timestamp.
boolean
When
true, only return posts from verified authors.Filter one community by query
This endpoint requires a search expression. It filters one community instead of returning 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 discover Communities, join them, or change membership. Use X’s Communities interface to discover groups and confirm participation rules. Read the official X Communities guide for current discovery, visibility, and membership behavior.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.Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns
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 so the next run can
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. Treat the value
as 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/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 focused query produces cleaner tweet rows and simpler 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 perspectives.
Normalize each tweet into explicit 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 preserve 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. This protects downstream
spreadsheets when a worker retries the last completed page.
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 instead. This
keeps each cursor tied to one understandable 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 reveals 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. This makes a CSV or XLSX file understandable without the original job logs. When a run stops early, label it partial. Preserve the last durable cursor for resumption. 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 two 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. This preserves understandable comparisons across collection windows. 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. This lets another analyst reproduce the search parameters without opening application logs. Version the manifest when a query changes. Keep earlier exports immutable. This preserves comparisons between research periods and prevents silent rewrites.Compare latest and top results without mixing datasets
RunLatest and Top as independent searches when research needs both views.
They answer different questions 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 two modes. Changing another input
would invalidate the comparison.
Use Latest to capture recent discussion. Record when the first page was
requested. New tweets can appear while later pages are collected.
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.
- Duplicate tweet IDs are removed within each run.
- Partial runs remain clearly 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 outside the visible tweet list. Bind it to the community,
query, sort mode, and page size. Disable the next-page action during requests.
Disable it permanently when has_next_page becomes false.
Treat an empty page as a valid search result. It does not mean the community
is missing. Display empty matches separately from authentication, credit, and
request errors.
Preserve decisions across a live moderation queue
Create one queue identity from the community ID, query, and sort mode. Keep it unchanged while reviewers page through matching tweets. Store each decision againsttweet.id. Never attach labels to visible row
numbers. New tweets can change result order between Latest requests.
Separate four queue states:
- Unreviewed tweets from the current cursor page.
- Selected tweets awaiting an explicit action.
- Reviewed tweets with a stored decision and review time.
- Failed page requests that retain their previous cursor.
Latest as a moving queue. Deduplicate incoming rows by Tweet ID. Keep
earlier decisions when the same tweet appears again.
Treat Top as a relevance review. Record each collection time because ranking
can change. Do not compare row positions across separate requests.
Pass approved Tweet IDs into reply, thread, profile, or media workflows. Keep
each follow-up response separate from the search result. Your queue owns the
reviewer, decision, and review time fields.
Build a query-specific community review batch
Save the exact query before requesting tweets. Preserve every operator, quoted phrase, exclusion, language choice, and engagement filter. Reviewers must see the expression that produced the queue. Store Tweet ID, author ID, text, creation time, engagement, and media for every match. Add the request time and returned cursor. Keep reviewer fields in a separate table keyed by Tweet ID. Assign one purpose to each batch. Examples include campaign replies, support complaints, product feedback, rule violations, or event coverage. Never mix unrelated queries inside one review queue. Persist each cursor page before requesting another. Deduplicate repeated Tweet IDs after retries. Never discard a prior decision when engagement counts change. Record one terminal state: completed, capped, credit-bounded, or interrupted. A live search page never proves a complete historical 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. Test the expression before opening a long queue. Inspect several Tweet IDs, authors, timestamps, replies, reposts, likes, and media URLs. Narrow recurring false matches with supported operators. Compare two queries with the same time window and result cap. Count unique Tweet IDs for each expression. Report overlapping matches separately. Never combine both result sets under one unrecorded query label.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.
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.
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.
- 200
- 400
- 401
- 402
- 424
- 429
- 502
Twitter community search API & keyword tweet results