Skip to main content
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.
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. 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?

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 build one row per matching community tweet. They do not print the full response page. Store 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. 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 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 starts a different result set. 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 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 changing q 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

Run Latest 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.
Use the combined view to decide what to research first. Keep the separate exports so others can reproduce and audit the work.

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.
Bind 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 against tweet.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[]
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

You exceeded your tier rate limit. 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.