Target Audience Discovery

Find relevant people on X (Twitter) using six discovery techniques. Each starts from a different signal: profile keywords, followers, Community membership, recent tweets, verification status, or engagement with a specific post. Combine the results by user ID to build a deduplicated audience. For a narrative walkthrough, see How to Find Your Target Audience on Twitter Using the API.

Choose a technique

Question	Endpoint	Result
Who describes themselves with a relevant role or keyword?	`POST /search-users`	User profiles
Who follows an account in my space?	`GET /followers`	Up to 200 profiles per page
Who joined a Community around my topic?	`POST /community-members`	Compact member profiles
Who is discussing my topic?	`POST /search-tweets`	Up to 20 tweets per page, with author profiles
Which verified accounts follow a target?	`GET /verified-followers`	Up to 200 profiles per page
Who amplifies a specific post?	`POST /retweeters`, `POST /quotes`	Retweeter profiles or quote tweets

Page sizes vary. Use next_cursor to continue; do not treat a short page as the end.

Setup and shared pagination

All examples use https://api.sorsa.io/v3 and require the ApiKey header. Run Python examples in the same script after this setup. Install requests with python -m pip install requests, then set the SORSA_API_KEY environment variable. JavaScript examples require a server-side runtime with fetch, such as Node.js 18 or later.

import os
import time
import requests

API_KEY = os.environ["SORSA_API_KEY"]
BASE_URL = "https://api.sorsa.io/v3"

def fetch_pages(method, endpoint, payload, result_key, max_pages=10):
    """Fetch a bounded number of pages; raise on HTTP errors."""
    items = []
    cursor = None
    seen_cursors = set()

    for _ in range(max_pages):
        values = dict(payload)
        if cursor:
            values["next_cursor"] = cursor
        options = {"params": values} if method == "GET" else {"json": values}
        response = requests.request(
            method, f"{BASE_URL}{endpoint}",
            headers={"ApiKey": API_KEY}, timeout=30, **options,
        )
        response.raise_for_status()
        data = response.json()
        items.extend(data.get(result_key) or [])
        cursor = data.get("next_cursor")
        if not cursor:
            break
        if cursor in seen_cursors:
            raise RuntimeError("Pagination returned a repeated cursor")
        seen_cursors.add(cursor)
        time.sleep(0.1)

    return items

max_pages limits request usage; reaching it can leave more results unread. These examples stop on HTTP errors. For production jobs, add bounded retries for 429 and transient server errors using Error Codes, and coordinate all workers that share a key under the rate limit. See Authentication and Pagination for shared mechanics.

Technique 1: Bio Keyword Search

Endpoint: POST /v3/search-users Search for accounts by keyword or phrase, such as a role, title, or interest. Inspect the returned bio, display name, and handle to decide whether each result matches your audience.

{
  "query": "Product Manager"
}

Parameter	Type	Required	Description
`query`	string	Yes	Search keyword or phrase.
`next_cursor`	string	No	Cursor from the previous response; omit on the first request.

Python

def find_users_by_bio(query, max_pages=10):
    return fetch_pages("POST", "/search-users", {"query": query}, "users", max_pages)

bio_results = find_users_by_bio("machine learning engineer")
qualified = [
    u for u in bio_results
    if (u.get("followers_count") or 0) >= 1000
    and (u.get("tweets_count") or 0) >= 100
    and not u.get("protected", False)
]

JavaScript

const API_KEY = process.env.SORSA_API_KEY;
if (!API_KEY) throw new Error("Set SORSA_API_KEY before running this example");

async function findUsersByBio(query, maxPages = 10) {
  const users = [];
  const seenCursors = new Set();
  let cursor = null;

  for (let i = 0; i < maxPages; i++) {
    const body = { query };
    if (cursor) body.next_cursor = cursor;
    const response = await fetch("https://api.sorsa.io/v3/search-users", {
      method: "POST",
      headers: { ApiKey: API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(30000),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    users.push(...(data.users || []));
    cursor = data.next_cursor;
    if (!cursor) break;
    if (seenCursors.has(cursor)) throw new Error("Repeated pagination cursor");
    seenCursors.add(cursor);
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  return users;
}

Technique 2: Competitor Follower Extraction

Endpoint: GET /v3/followers Retrieve followers of a relevant public account, up to 200 profiles per request. Provide one of username (without @), user_id (a string), or user_link (a full profile URL). Pass an optional next_cursor to continue.

GET https://api.sorsa.io/v3/followers?username=competitor_handle

def get_followers(username, max_pages=10):
    return fetch_pages("GET", "/followers", {"username": username}, "users", max_pages)

followers = get_followers("competitor_handle", max_pages=20)

Overlap across multiple seed accounts

Count each user once per seed account. Replace the placeholder handles before running:

from collections import Counter

competitors = ["competitor_a", "competitor_b", "competitor_c"]
follower_sets = {
    handle: {u["id"] for u in get_followers(handle, max_pages=10)}
    for handle in competitors
}
counts = Counter(uid for ids in follower_sets.values() for uid in ids)
overlap = {uid for uid, count in counts.items() if count >= 2}

This measures overlap in the pages you retrieved, not necessarily the full follower lists. See Followers and Following for a deeper walkthrough.

Technique 3: Community Member Discovery

Check availability first: This section documents the Community request format. Confirm current data availability with support before adding it to a new workflow; see Lists and Communities.

Endpoint: POST /v3/community-members Retrieve the members of an X Community. Membership is a useful interest signal, but does not establish current activity or purchase intent.

{
  "community_link": "1966045657589813686"
}

community_link accepts the numeric ID as a string or a full Community URL.

def get_community_members(community_id, max_pages=20):
    return fetch_pages(
        "POST", "/community-members",
        {"community_link": community_id}, "users", max_pages,
    )

The response contains compact profiles: id, username, display_name, profile_image_url, verified, and protected. Before filtering on bio or follower counts, enrich the IDs through User Profile (Batch), up to 100 IDs per call. See Lists and Communities for related endpoints.

Technique 4: Intent-Based Tweet Mining

Endpoint: POST /v3/search-tweets Search recent discussions and extract unique authors. Keep each full user object so it can be combined with profile and follower results later.

def find_active_voices(query, min_followers=100, max_pages=10):
    tweets = fetch_pages(
        "POST", "/search-tweets",
        {"query": query, "order": "latest"}, "tweets", max_pages,
    )
    voices = {}
    for tweet in tweets:
        user = tweet.get("user")
        if not user or not user.get("id"):
            continue
        if (user.get("followers_count") or 0) < min_followers:
            continue
        if user["id"] not in voices:
            voices[user["id"]] = {
                **user,
                "sample_tweet": (tweet.get("full_text") or "")[:160],
            }
    return list(voices.values())

intent_voices = find_active_voices(
    '("need a CRM" OR "looking for a CRM") lang:en -filter:retweets',
)

Common query patterns

Replace bracketed placeholders with your category, handle, tool, or topic. Parentheses keep shared filters attached to both sides of OR.

Goal	Query
Buying intent	`("need a [category]" OR "looking for [category]") lang:en -filter:retweets`
Competitor frustration	`"[competitor]" (frustrated OR broken OR "switching from") -from:[competitor]`
Migration intent	`("migrating from [tool]" OR "switching from [tool]") lang:en`
Recommendation requests	`("any recommendation" OR "anyone use") [topic] lang:en`
Pain-point discussion	`("struggling with" OR "how do you handle") [topic] lang:en`

For a defined observation window, add since: and until: filters. Review the matching posts before treating a keyword match as buying intent. See Search Operators and Search Tweets.

Technique 5: Verified Follower Analysis

Endpoint: GET /v3/verified-followers Retrieve verified followers using the same identifier and pagination pattern as /followers. Verification status is a segment attribute; assess relevance separately.

def get_verified_followers(username, max_pages=10):
    return fetch_pages(
        "GET", "/verified-followers", {"username": username}, "users", max_pages,
    )

verified = get_verified_followers("openai")
verified.sort(key=lambda u: u.get("followers_count") or 0, reverse=True)

Technique 6: Retweeters and Quoters

Endpoints: POST /v3/retweeters, POST /v3/quotes /retweeters returns user profiles. /quotes returns quote tweet objects, with the quoting user in user and their commentary in full_text.

def get_retweeters(tweet_link, max_pages=10):
    return fetch_pages(
        "POST", "/retweeters", {"tweet_link": tweet_link}, "users", max_pages,
    )

def get_quoters(tweet_link, max_pages=10):
    quote_tweets = fetch_pages(
        "POST", "/quotes", {"tweet_link": tweet_link}, "tweets", max_pages,
    )
    return list({
        tweet["user"]["id"]: tweet["user"]
        for tweet in quote_tweets if tweet.get("user")
    }.values())

The helper get_quoters converts quote tweets into unique user profiles for the workflow below. If you need commentary, keep the original quote_tweets and analyze full_text before this conversion.

Combining Techniques

Combine lists of user objects by string ID, preserving the set of sources for each account. A higher source count means an account appeared in more of your selected inputs; it is a prioritization heuristic, not a confidence score.

def score_by_source(by_source):
    index = {}
    for source, users in by_source.items():
        for user in users:
            uid = user["id"]
            if uid not in index:
                index[uid] = {"user": dict(user), "sources": set()}
            else:
                # Fill gaps when one source returns a compact profile.
                for field, value in user.items():
                    if index[uid]["user"].get(field) is None and value is not None:
                        index[uid]["user"][field] = value
            index[uid]["sources"].add(source)

    result = [
        {**entry["user"], "source_count": len(entry["sources"]),
         "sources": sorted(entry["sources"])}
        for entry in index.values()
    ]
    return sorted(result, key=lambda u: (-u["source_count"], -(u.get("followers_count") or 0)))

# Uses the results from Techniques 1, 2, and 4 above.
combined = score_by_source({
    "profile_search": bio_results,
    "competitor_followers": followers,
    "topic_discussion": intent_voices,
})

Add Community members after enriching their compact profiles. You can also add the user lists returned by get_retweeters and get_quoters.

Filtering for Quality

Use explicit selection criteria for your project. This filter checks profile completeness, account age, and basic counts. It does not detect bots or establish recent activity; inspect recent tweets when activity matters.

from datetime import datetime, timezone, timedelta

def is_quality_account(user, min_followers=500, min_tweets=100, max_following_ratio=10):
    if user.get("protected", False):
        return False
    followers = user.get("followers_count") or 0
    if followers < min_followers or (user.get("tweets_count") or 0) < min_tweets:
        return False
    if (user.get("followings_count") or 0) > followers * max_following_ratio:
        return False
    if not (user.get("description") or "").strip():
        return False

    created = user.get("created_at")
    if not created:
        return False
    try:
        dt = datetime.fromisoformat(created.replace("Z", "+00:00"))
        if dt.tzinfo is None:
            return False
    except (TypeError, ValueError):
        return False
    return dt <= datetime.now(timezone.utc) - timedelta(days=30)

qualified = [user for user in combined if is_quality_account(user)]

Accounts with missing or unparseable creation dates are excluded by this example. Adjust that policy and the thresholds to your use case.

Exporting to CSV

Export user objects after deduplication and filtering. Convert tweet results to their user objects first; enrich compact Community profiles if you need the missing fields.

import csv

def export_users_to_csv(users, output_file="audience.csv"):
    fields = [
        "user_id", "username", "display_name", "description",
        "followers_count", "followings_count", "tweets_count",
        "location", "verified", "created_at",
    ]
    with open(output_file, "w", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=fields)
        writer.writeheader()
        for user in users:
            row = {field: user.get(field, "") for field in fields}
            row["user_id"] = user["id"]
            row["description"] = (user.get("description") or "").replace("\n", " ")
            writer.writerow(row)

export_users_to_csv(qualified)

Missing values remain blank rather than becoming zero. When importing the CSV into a spreadsheet, set the user_id column to text to preserve the full ID.

Next Steps

Search Tweets — request parameters and tweet search examples.
Search Operators — Boolean logic and filters.
Followers and Following — follower analysis.
Lists and Communities — membership and feed endpoints.
Competitor Analysis — competitive intelligence workflows.
Real-Time Monitoring — polling and deduplication.
Track Mentions — mentions of brands and competitors.
Optimizing API Usage — batching and request budgeting.
API Reference — endpoint specifications.

Getting started

Core Mechanics

Solution Guides

Support & Resources

Choose a technique

Technique 1: Bio Keyword Search

Python

JavaScript

Technique 2: Competitor Follower Extraction

Overlap across multiple seed accounts

Technique 3: Community Member Discovery

Technique 4: Intent-Based Tweet Mining

Common query patterns

Technique 5: Verified Follower Analysis

Technique 6: Retweeters and Quoters

Combining Techniques

Filtering for Quality

Exporting to CSV

Next Steps

​Choose a technique

​Setup and shared pagination

​Technique 1: Bio Keyword Search

​Python

​JavaScript

​Technique 2: Competitor Follower Extraction

​Overlap across multiple seed accounts

​Technique 3: Community Member Discovery

​Technique 4: Intent-Based Tweet Mining

​Common query patterns

​Technique 5: Verified Follower Analysis

​Technique 6: Retweeters and Quoters

​Combining Techniques

​Filtering for Quality

​Exporting to CSV

​Next Steps

Choose a technique

Setup and shared pagination

Technique 1: Bio Keyword Search

Python

JavaScript

Technique 2: Competitor Follower Extraction

Overlap across multiple seed accounts

Technique 3: Community Member Discovery

Technique 4: Intent-Based Tweet Mining

Common query patterns

Technique 5: Verified Follower Analysis

Technique 6: Retweeters and Quoters

Combining Techniques

Filtering for Quality

Exporting to CSV

Next Steps