X Spaces API：主持人、发言人和听众数

#Space 查询会返回什么，以及哪些数据没有任何 API 能返回

Space 查询针对一个 Space 返回三类信息：它是什么（标题、状态、预定开始时间和开始时间），谁在主持（主持人、共同主持人和发言人），以及有多少人在听。除此之外没有别的：没有音频，没有文字记录，也没有完整的听众名单。想看 API 能读取的其他各类 X 数据，能从 Twitter API 获取哪些数据这张图把它们并排列了出来。

X 自己的开发者平台通过 GET /2/spaces/{id} 以及它的批量版本和按创建者查询的版本读取 Space。它的 Spaces 文档（在新标签页打开）给出三个会影响任何项目的限制：

• 听众只以数字出现。 participant_count 字段统计房间里的所有人，包括主持人；没有听众名单。
• 人只以 ID 出现。 主持人、共同主持人和发言人返回的是用户 ID，要拿到他们的资料只能通过 expansions。
• 已结束的 Space 就没了。 Space 一结束，Spaces 接口就返回错误，而不是返回这个 Space。

价格见 X 的按量付费价目表（在新标签页打开）：每次读取一个 Space $0.005，每 1,000 个 $5.00。自 2026 年 11 月 22 日起，通过 expansion 返回的每份用户资料也要计费，每份 $0.010（见 X 在 10 月 23 日的通知（在新标签页打开）），所以带着主持人资料的 Space 每个 $0.015。每次调用还需要开发者账号、预付额度，以及 OAuth 2.0 或 bearer 令牌。

听众名单拿不到，并不是 X 的 API 小气。Space 是公开的，而且 X 帮助中心（在新标签页打开）说，未登录收听的人可能根本不会作为嘉宾出现在房间里。听众数量是可靠的数据；而一份包含每位听众的名单，在任何地方都不存在。

#用 Sorsa API 获取 Space 的详情

要用代码读取 X Space，请用 Sorsa API，一款 Twitter（X）API 与爬虫：GET /spaces 接收 Space ID 或链接，一次请求就返回标题、状态和时间、主持人的完整资料、共同主持人和发言人，以及直播和回放的计数，每 1,000 个 Space $1.40 起。所有套餐都是每秒 20 次请求，只需一个 API 密钥，不用开发者账号。

1. 获取密钥。 注册后，从控制台复制你的 API 密钥。送的 100 次免费请求可以查询 100 个 Space。

2. 复制 Space ID。 Space ID 是 Space 链接里 /i/spaces/ 后面由字母和数字组成的代码：在 x.com/i/spaces/1yNxaYzQkPwKj 中，它是 1yNxaYzQkPwKj。X 把它限制在 13 个字符以内，它不是帖子那种很长的数字。

3. 发送请求。 调用 GET /spaces（在新标签页打开），把 ID 作为 id，或者把整个链接作为 link 传入，并在 ApiKey 请求头里带上密钥。

   curl -G "https://api.sorsa.io/v3/spaces" \
     -H "ApiKey: YOUR_API_KEY" \
     --data-urlencode "id=1yNxaYzQkPwKj"
   

4. 读取响应。 返回一个 JSON 对象：Space 自身的字段在最上层，creator 是主持人的完整资料，participants 按角色列出人员，stats 是听众数据，settings 是回放和访问相关的标志。

   {
     "id": "1yNxaYzQkPwKj",
     "title": "Shipping hardware in Q1: founders compare notes",
     "state": "Running",
     "scheduled_start": 1793642400000,
     "created_at": 1793641912000,
     "updated_at": 1793645530000,
     "media_key": "28_1793641912057",
     "is_subscribed": false,
     "creator": {
       "id": "1630218874471563264",
       "username": "harbor_founders_live",
       "display_name": "Harbor Founders",
       "description": "Weekly live audio for people who ship hardware.",
       "followers_count": 48210,
       "followings_count": 312,
       "verified": true,
       "protected": false,
       "created_at": "2023-02-27T14:05:11Z",
       "profile_image_url": "https://pbs.twimg.com/profile_images/1630/harbor.jpg"
     },
     "participants": {
       "admins": [
         {
           "id": "1630218874471563264",
           "username": "harbor_founders_live",
           "name": "Harbor Founders",
           "is_verified": true,
           "start": 1793642405000
         },
         {
           "id": "1488230561123123200",
           "username": "maren_builds_hardware",
           "name": "Maren Holt",
           "is_verified": false,
           "start": 1793642460000
         }
       ],
       "speakers": [
         {
           "id": "1712093345678901248",
           "username": "tomas_ships_firmware",
           "name": "Tomas Reyes",
           "is_verified": false,
           "is_muted_by_admin": false,
           "start": 1793643120000
         }
       ],
       "listeners": [],
       "total": 1286
     },
     "stats": {
       "total_live_listeners": 1183,
       "total_participants": 1286,
       "total_replay_watched": 0
     },
     "settings": {
       "is_space_available_for_replay": true,
       "is_space_available_for_clipping": true,
       "is_locked": false,
       "disallow_join": false,
       "max_admin_capacity": 3
     }
   }
   

   显示完整响应

同样的调用，用 Python 和 Node.js 写出来，可以直接套进循环处理一批 Space：

import requests

API = "https://api.sorsa.io/v3"
HEADERS = {"ApiKey": "YOUR_API_KEY"}

def get_space(space_id):
    r = requests.get(f"{API}/spaces", headers=HEADERS,
                     params={"id": space_id}, timeout=30)
    r.raise_for_status()
    return r.json()

space = get_space("1yNxaYzQkPwKj")
people = space["participants"]
print(space["title"], "|", space["state"])
print("Host:", space["creator"]["username"])
print("Admins:", [p["username"] for p in people["admins"]])
print("Speakers:", [p["username"] for p in people["speakers"]])
print("Live listeners:", space["stats"]["total_live_listeners"])

const url = "https://api.sorsa.io/v3/spaces?id=1yNxaYzQkPwKj";
const res = await fetch(url, {
  headers: { ApiKey: "YOUR_API_KEY" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const space = await res.json();
const speakers = space.participants.speakers.map((p) => p.username);
console.log(space.title, space.state);
console.log("Speakers:", speakers);
console.log("Live listeners:", space.stats.total_live_listeners);

ID 错误或不存在时返回 404，密钥缺失或额度用完时返回 403，失败的请求从不收费。每秒超过 20 次请求会返回 429：等一秒再发即可。

#回答“谁”和“多少”的字段

大多数 Space 项目只读五个字段：谁主持，谁发言，有多少人在线收听，有多少人看了回放，以及状态。下面的图把整个响应按每部分回答的问题分了组。

如果你要把代码从官方 X API 迁移过来，字段的对应关系如下：

• 谁发起了 Space

  Sorsa API 字段

  creator，完整资料

  官方 X API 字段

  creator_id，资料只能通过 expansions 获得

• 主持人和共同主持人

  Sorsa API 字段

  participants 里的 admins，带用户名和名称

  官方 X API 字段

  host_ids

• 发言人

  Sorsa API 字段

  participants 里的 speakers，带用户名和名称

  官方 X API 字段

  speaker_ids

• 听众规模

  Sorsa API 字段

  stats 里的 total_live_listeners 和 total_participants

  官方 X API 字段

  participant_count

• 回放观看数

  Sorsa API 字段

  stats 里的 total_replay_watched

  官方 X API 字段

  无

• 已预定还是正在直播

  Sorsa API 字段

  state、scheduled_start

  官方 X API 字段

  state、scheduled_start、started_at

• 是否允许回放和剪辑

  Sorsa API 字段

  settings 里的两个标志

  官方 X API 字段

  无

有个细节能省下调试时间：Space 对象里的时间是 Unix 时间戳（纯数字），而 Sorsa API 的其余部分用 ISO 8601 日期，上面的 creator.created_at 就是这样。

须知

请把 participants.listeners 当作房间碰巧显示出来的人，而不是出勤表：X 只列出一部分听众，未登录的听众从不出现。要知道听众规模，请读 stats.total_live_listeners，它统计的是所有人。

admins 和 speakers 带有用户名、名称和认证标志，主持人则带有完整资料。如果你需要台上每个人的粉丝数和简介，把他们的用户名传给 GET /info-batch（在新标签页打开）：一次请求最多 100 份资料，每 1,000 份 $0.014 起。

#找到要查询的 Space：搜索链接到它们的帖子

查询 Space 需要 ID，而找 ID 的地方就是 X 本身：主持人会在帖子里宣传自己的 Space，每条这样的帖子都带着 Space 的链接。Sorsa API 的 POST /search-tweets（在新标签页打开） 配合 filter:spaces 运算符，只返回包含 Space 链接的帖子，每次约 20 条，覆盖回溯到 2006 年的完整归档。

查询语句用你在推特搜索运算符指南里已经学过的运算符来组合：

• from:harbor_founders_live filter:spaces 找出某位主持人分享过的所有 Space。
• "hardware" filter:spaces since:2026-10-01 找出 10 月以来某个主题的 Space。
• (from:host_one_on_stage OR from:host_two_on_stage) filter:spaces 盯住一小组主持人。

下面的脚本用 next_cursor 逐页翻看结果，从每条帖子的正文和链接里提取 Space ID，再用上一步的 get_space() 逐个查询：

import re
import requests

API = "https://api.sorsa.io/v3"
HEADERS = {"ApiKey": "YOUR_API_KEY"}
SPACE_LINK = re.compile(r"/i/spaces/([A-Za-z0-9]{1,13})")

def find_space_ids(query, max_pages=5):
    ids, cursor = set(), None
    for _ in range(max_pages):
        body = {"query": query, "order": "latest"}
        if cursor:
            body["next_cursor"] = cursor
        r = requests.post(f"{API}/search-tweets", headers=HEADERS,
                          json=body, timeout=30)
        r.raise_for_status()
        page = r.json()
        for post in page.get("tweets", []):
            links = [e.get("link") or "" for e in post.get("entities", [])]
            for text in [post["full_text"], *links]:
                ids.update(SPACE_LINK.findall(text))
        cursor = page.get("next_cursor")
        if not cursor:
            break
    return ids

for space_id in find_space_ids("from:harbor_founders_live filter:spaces"):
    space = get_space(space_id)
    print(space_id, space["state"], space["title"],
          space["stats"]["total_live_listeners"])

每个搜索页和每次查询都算一次请求。搜索五页、找到 30 个 Space，一共 35 次请求，按每秒 20 次请求，整个过程几秒就跑完。

#跟踪正在进行的 Space：听众数随时间的变化

想看一个 Space 的听众怎样增长、怎样退去，就在它直播期间按计划反复查询同一个 Space，并把每次读数存下来。每次查询都返回当前的 state、在线听众数和台上的人，所以一串读数就是这个 Space 的听众曲线。

import time
from datetime import datetime, timezone

def track(space_id, every_seconds=180, checks=30):
    for _ in range(checks):
        space = get_space(space_id)
        now = datetime.now(timezone.utc).strftime("%H:%M")
        stage = len(space["participants"]["speakers"])
        print(now, space["state"],
              space["stats"]["total_live_listeners"], stage)
        time.sleep(every_seconds)

track("1yNxaYzQkPwKj")

一个 90 分钟的 Space 每 3 分钟查一次，需要 30 次请求，按 Pro 套餐每 1,000 次 $1.99 计算，约 $0.06。Sorsa API 的每次请求都是实时应答，所以每次检查看到的，都是房间在那一刻的样子。下面的计算器会把你的 Space 数量和检查次数换算成请求数，以及能覆盖它们的套餐：

如果想在被关注的账号发帖时收到提醒，包括开启 Space 的那条帖子，推特实时监测指南展示了大规模轮询的循环；公开的 X List 则能让一次请求读取最多 5,000 位主持人的最新帖子，详见 Twitter List API 指南。

#X Spaces 数据的成本：Sorsa API 与官方 X API 对比

在 Sorsa API 上，不论 Space 里有什么，一次查询都只算一次请求，每 1,000 个 Space $1.40 起，包含主持人的完整资料。在官方 X API 上，同样带着主持人资料的 Space，自 2026 年 11 月 22 日起每个 $0.015，也就是每 1,000 个 $15.00。

在官方 X API 上，每多展开一位共同主持人或发言人，就多收 $0.010，所以台上有五个人的 Space 在那里要 $0.055；Sorsa API 在同一次请求里就返回这些人。价格只是决定 Spaces 项目的五件事之一，Sorsa API 对每一件事的回答都是一个数字：

• 每 1,000 个 Space 的价格： Sorsa API 上每 1,000 个 $1.40 起，官方 X API 上光是 Space 本身是 $5.00，带主持人是 $15.00。
• 人员： 主持人的完整资料、共同主持人和发言人都在同一个响应里；台上每个人的完整资料，每多一次请求可查 100 份。
• 听众数据： 在线听众、全部参与者和回放观看数，而官方 X API 只有一个参与者数。
• 查找 Space： 用 filter:spaces 搜索回溯到 2006 年的帖子，所以不会只局限于别人发给你的链接。
• 接入和速度： 请求头里放一个 API 密钥，不用开发者账号，也不用 OAuth，所有套餐都是每秒 20 次请求，所以 1,000 个 Space 不到一分钟就能查完。

Sorsa API 从设计上就是只读，也从不要求你的 X 登录信息，所以你自己的 X 账号永远不会有风险。要创建或主持 Space，请用 X 的应用；要发帖宣传它们，请把 Sorsa API 和官方 X API 搭配使用。

#查询你的第一个 Space

X Space 的主持人、发言人和听众数，只需用链接里的 ID 查询一次，而官方 X API 在 Space 结束后就什么也不返回了。Sorsa API 一次请求就能读取同一个 Space，带上主持人的完整资料以及直播和回放的计数，每 1,000 个 Space $1.40 起，还能通过搜索帮你找到 Space。你的 100 次免费请求可以查询 100 个 Space：把一个 Space 链接粘贴到上面的请求里，运行即可。

#常见问题