x/
search-communities

Use the X Communities Search API to find communities by keyword and get each match's name, link, banner image, member count and sensitive-content flag, with up to 500 communities per query.

X Communities Search API

Keyword input
Member count per community
Sensitive-content flag
0.7 credits / result
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

X Communities Search

X communities are topic groups that people join on X, and in a search listing each one shows a name, a banner image, a member count and a flag for whether it is marked as sensitive. Running a keyword against those listings reveals where a subject is being discussed, which groups are the largest, and which carry an adult or sensitive label before anyone opens them.

X Communities Search API Features

  • One keyword, every matching communityPut a word or phrase in query, such as bitcoin, and the X Communities Search API returns the communities X lists for it, one row each.
  • Name and bannername and cover_url give the title and banner image of each community, enough to recognise it in a list or show it in your own interface.
  • Member count for sizingmetrics.members_count tells you how many people have joined, so a tiny group and a community of tens of thousands can be told apart straight from the search.
  • Sensitive-content markeris_nsfw is true when the community is marked as sensitive on X, which lets you handle adult spaces before they reach a report or a user.
  • Stable ID and linkEach row carries the numeric community id and its https://x.com/i/communities/<id> url, which stay the same across searches and work as a key in your own data.

X Communities Search API Parameters

ParametersRequiredDescription
queryRequiredThe keyword to search X communities for, such as bitcoin.
results_limitOptionalHow many communities to return, a multiple of 10 from 10 to 500. Defaults to 20.

How to Use the X Communities Search API

Search a keyword with the X Communities Search API and page through the communities it matches.

  1. POST {"query": "bitcoin", "results_limit": 20} to /v1/x/search-communities.
  2. Poll GET /v1/tasks/{task_id} until status is succeeded.
  3. Read matching communities from results.items; while has_more is true, request the next page with results.next_cursor.
curl -X POST "https://api.socq.ai/v1/x/search-communities" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bitcoin","results_limit":20}'

# Each result's url can go straight into X Community Members, X Community Moderators or X Community Posts.

X Communities Search API Use Cases

  • Mapping where a topic lives on X: Search the main terms of a market or hobby and collect the community names, links and member counts that show where its conversation gathers.
  • Shortlisting the biggest communities in a niche: Sort the X Communities Search API matches by metrics.members_count to pick the few communities large enough to be worth a sponsorship, a post or a closer look.
  • Keeping community lists brand-safe: Drop every row where is_nsfw is true before a list of communities is shared with a client or shown inside a product.
  • Feeding member and moderator exports: Pass the url of each shortlisted community to X Community Members or X Community Moderators to move from a list of groups to the people in them.

X Communities Search API Pro Tips

  • Run close variants of a term, such as bitcoin and btc, and merge the results on id, because one community can match several keywords.
  • To follow how communities grow, repeat the same X Communities Search API query on a schedule and store metrics.members_count with collected_at under each id.

Beyond the X Communities Search API, use these APIs when you need a different type of public X data.

  • Twitter Search API — Find public posts by search expression with latest or top ordering and a configurable result limit.
  • X Trends API — Collect current public X trend snapshots for known numeric WOEIDs with source rank, query, description, and location context.
  • Twitter User Search API — Find public X accounts by keyword.
  • X Community API — Read community links for descriptions, membership counts, rules and joining policies.
  • X Community Posts API — Read the public posts shared in a community, with their text, authors and interaction counts.
  • X Community Members API — Export a community's members as full profiles with bios and follower counts.

Explore other platforms

Combine X data with public data from other supported social platforms.

X Communities Search API — FAQ

X Communities Search API is a programmatic interface for finding X communities that match a keyword. It returns each community's id, url, name, banner image, member count and sensitive-content flag.

Send the keyword in query, for example bitcoin. The matching communities come back with their names, links and member counts, ready to open on X or pass to another community endpoint.

Yes, in your own code. Every result includes metrics.members_count, so collect the matches first and then sort them or apply a minimum size.

Up to 500. results_limit takes multiples of 10 from 10 to 500 and defaults to 20; read the results page by page with next_cursor.

It is true when X marks the community as containing sensitive content, and false otherwise.

No. Search results list the name, banner, member count and sensitive flag. Pass the url to X Community API to get the description, rules and joining policies.

No community matched it. The task still succeeds with an empty result, and nothing is charged.