发现目标受众

通过六种方法在 X（Twitter）发现相关用户。每种方法从不同信号出发：资料关键词、粉丝、社群成员身份、近期推文、认证状态或特定帖子的互动。按用户 ID 合并结果，构建去重后的受众列表。详细教程见如何通过 API 在 Twitter 找到目标受众。

选择方法

问题	端点	结果
谁用相关职位或关键词描述自己？	`POST /search-users`	用户资料
谁关注了我所在领域的账号？	`GET /followers`	每页最多 200 份资料
谁加入了相关主题的社群？	`POST /community-members`	精简成员资料
谁正在讨论我的话题？	`POST /search-tweets`	每页最多 20 条推文，含作者资料
哪些认证账号关注了目标？	`GET /verified-followers`	每页最多 200 份资料
谁在传播特定帖子？	`POST /retweeters`、`POST /quotes`	转推者资料或引用推文

每页数量可能变化。使用 next_cursor 继续读取，不要把较短的页面视为末尾。

环境设置与通用分页

所有示例使用 https://api.sorsa.io/v3，并需要 ApiKey 请求头。Python 示例应放在下方初始化代码之后，在同一脚本中运行。使用 python -m pip install requests 安装 requests，然后设置 SORSA_API_KEY 环境变量。JavaScript 示例需要支持 fetch 的服务端环境，例如 Node.js 18 或更高版本。

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 限制请求用量，达到上限时可能仍有结果未读取。示例遇到 HTTP 错误会停止。生产任务应参照错误码，对 429 和临时服务器错误加入有限重试，并根据速率限制统一协调共享密钥的工作进程。通用机制见身份验证和分页。

方法 1：简介关键词搜索

端点：POST /v3/search-users 按职位、头衔、兴趣等关键词或短语搜索账号。检查返回的简介、显示名称和用户名，判断结果是否符合目标受众。

{
  "query": "Product Manager"
}

参数	类型	必需	说明
`query`	string	是	搜索关键词或短语。
`next_cursor`	string	否	上一响应的游标，首次请求省略。

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;
}

方法 2：提取竞争对手粉丝

端点：GET /v3/followers 获取相关公开账号的粉丝，每次最多 200 份资料。提供 username（不含 @）、user_id（字符串）或 user_link（完整资料 URL）其中一种。需要继续时传入可选的 next_cursor。

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)

多个种子账号的受众重叠

对于每个种子账号，每位用户只计数一次。运行前替换示例中的占位用户名：

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}

这衡量的是已获取页面中的重叠，并不一定涵盖完整粉丝列表。详细教程见粉丝与关注。

方法 3：发现社群成员

先检查可用性： 本节介绍社群请求格式。加入新工作流前，请向支持团队确认当前数据可用性，详情见列表与社群。

端点：POST /v3/community-members 获取 X 社群成员。成员身份是有用的兴趣信号，但不能证明当前活跃度或购买意图。

{
  "community_link": "1966045657589813686"
}

community_link 接受字符串形式的数字 ID 或完整社群 URL。

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

响应包含精简资料：id、username、display_name、profile_image_url、verified 和 protected。按简介或粉丝数筛选前，应通过批量用户资料补全这些 ID，每次最多 100 个。相关端点见列表与社群。

方法 4：根据意图挖掘推文

端点：POST /v3/search-tweets 搜索近期讨论，提取去重后的作者。保留完整用户对象，便于随后与资料和粉丝结果合并。

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',
)

常见查询模式

将方括号中的占位内容替换为你的类别、用户名、工具或话题。括号确保共享筛选条件同时作用于 OR 两边。

目标	查询
购买意图	`("need a [category]" OR "looking for [category]") lang:en -filter:retweets`
对竞争对手的不满	`"[competitor]" (frustrated OR broken OR "switching from") -from:[competitor]`
迁移意图	`("migrating from [tool]" OR "switching from [tool]") lang:en`
寻求推荐	`("any recommendation" OR "anyone use") [topic] lang:en`
痛点讨论	`("struggling with" OR "how do you handle") [topic] lang:en`

限定观察窗口时，添加 since: 和 until:。将关键词匹配视为购买意图之前，应阅读匹配帖子。参阅搜索运算符和搜索推文。

方法 5：分析认证粉丝

端点：GET /v3/verified-followers 使用与 /followers 相同的标识符和分页方式获取认证粉丝。认证状态只是细分属性，相关性仍需单独评估。

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)

方法 6：转推者与引用者

端点：POST /v3/retweeters、POST /v3/quotes /retweeters 返回用户资料。/quotes 返回引用推文对象，其中 user 为引用者，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())

辅助函数 get_quoters 将引用推文转换为去重的用户资料，供下方工作流使用。如果需要评论内容，应保留原始 quote_tweets，并在转换之前分析 full_text。

组合多种方法

按字符串 ID 合并用户对象列表，同时为每个账号保留来源集合。来源数量更高表示该账号出现在更多选定输入中；这只是优先级参考，不是置信分数。

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,
})

补全精简资料后再加入社群成员，也可以加入 get_retweeters 和 get_quoters 返回的用户列表。

质量筛选

为项目制定明确的选择标准。以下筛选器检查资料完整度、账号年龄和基本计数，不会检测机器人，也不能证明近期活跃度。若活跃度重要，应查看近期推文。

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)]

示例会排除创建日期缺失或无法解析的账号。请根据使用场景调整这一策略和阈值。

导出到 CSV

去重和筛选后导出用户对象。先将推文结果转换为 user 对象；需要缺失字段时，先补全社群精简资料。

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)

缺失值保留为空，而不是变为零。导入电子表格时，将 user_id 列设为文本，以保留完整 ID。

后续步骤

搜索推文：请求参数与搜索示例
搜索运算符：布尔逻辑与筛选
粉丝与关注：粉丝分析
列表与社群：成员与信息流端点
竞品分析：竞品情报工作流
实时监测：轮询与去重
追踪提及：品牌和竞争对手的提及
优化 API 使用：批量和请求预算
API 参考：端点规范

入门

核心概念

实用指南

支持与资源

选择方法

环境设置与通用分页

方法 1：简介关键词搜索

Python

JavaScript

方法 2：提取竞争对手粉丝

多个种子账号的受众重叠

方法 3：发现社群成员

方法 4：根据意图挖掘推文

常见查询模式

方法 5：分析认证粉丝

方法 6：转推者与引用者

组合多种方法

质量筛选

导出到 CSV

后续步骤

​选择方法

​环境设置与通用分页

​方法 1：简介关键词搜索

​Python

​JavaScript

​方法 2：提取竞争对手粉丝

​多个种子账号的受众重叠

​方法 3：发现社群成员

​方法 4：根据意图挖掘推文

​常见查询模式

​方法 5：分析认证粉丝

​方法 6：转推者与引用者

​组合多种方法

​质量筛选

​导出到 CSV

​后续步骤

选择方法

环境设置与通用分页

方法 1：简介关键词搜索

Python

JavaScript

方法 2：提取竞争对手粉丝

多个种子账号的受众重叠

方法 3：发现社群成员

方法 4：根据意图挖掘推文

常见查询模式

方法 5：分析认证粉丝

方法 6：转推者与引用者

组合多种方法

质量筛选

导出到 CSV

后续步骤