Skip to main content
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.
Use Twitter community search to filter posts inside one known Community. Run a Twitter search in community posts with a numeric Community ID and query. Store Tweet IDs, authors, engagement counts, media, and cursors for exports.

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?

Send communityId 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
The Node.js & Python snippets shape one durable row per matching community tweet instead of printing the full response page. Persist the final 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

Use GET /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 Latest or Top.
  • A stable page size.
  • The time when collection started.
Keep those values beside every saved cursor. Resume with the same values. Changing the query during pagination creates a different result stream. Use 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 changing q 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

Run Latest 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.
Use the combined view for research prioritization. Preserve the independent exports for reproducibility and later audits.

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.
Keep 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 against tweet.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.
When a page fails, keep the current rows and cursor. Retry with identical query parameters. Do not advance the cursor until every row is durable. Treat 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[]
Lists media items attached to the Tweet. Omitted when none exist. Media object fields.
string
Provides the direct media URL.
object[]
Lists available video renditions and playback details. Omitted for images.
string
Identifies the attached media type.
string
Shortened URL from the tweet text.
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

The q query parameter is empty or missing.

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.
Missing or invalid API key.

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

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

Your tier rate limit was exceeded. Wait for the Retry-After header before retrying.

424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.
Next steps. Community Info to look up a community, or Search Tweets for general tweet search.