API de Spaces do X: hosts, oradores e número de ouvintes

#O que uma consulta de Space retorna, e o que nenhuma API retorna

Uma consulta de Space retorna três coisas sobre um Space: o que ele é (título, estado, horários de agendamento e de início), quem o comanda (o host, os co-hosts e os oradores) e quantas pessoas ouvem. Nada além disso volta: nem áudio, nem transcrição, nem uma chamada completa do público. Para todos os outros tipos de dados do X que uma API consegue ler, o mapa de quais dados você obtém da API do Twitter os lista lado a lado.

A plataforma de desenvolvedores do próprio X lê Spaces pelo GET /2/spaces/{id} e pelas versões em lote e por criador dele. A documentação de Spaces (abre em uma nova aba) do X impõe três limites que moldam qualquer projeto:

• Os ouvintes chegam como um número. O campo participant_count conta todos na sala, hosts inclusos; não existe lista de ouvintes.
• As pessoas chegam como IDs. O host, os co-hosts e os oradores voltam como IDs de usuário, e os perfis deles só por meio de expansions.
• Spaces encerrados somem. Quando um Space termina, os endpoints de Spaces retornam um erro em vez do Space.

O preço está na tabela de pagamento por uso do X (abre em uma nova aba): US$ 0,005 por leitura de Space, US$ 5,00 por 1.000. A partir de 22 de novembro de 2026, todo perfil de usuário que volta por uma expansion também é cobrado, a US$ 0,010 (aviso do X de 23 de outubro (abre em uma nova aba)), então um Space com o perfil do host custa US$ 0,015. Cada chamada ainda exige uma conta de desenvolvedor, créditos pré-pagos e um token OAuth 2.0 ou bearer.

O limite de ouvintes não é mesquinharia da API do X. Os Spaces são públicos, e a Central de Ajuda do X (abre em uma nova aba) diz que quem ouve sem estar logado pode nem aparecer como convidado na sala. Uma contagem de ouvintes é um dado sólido; uma lista de todos os ouvintes não existe em lugar nenhum.

#Obtenha os detalhes de um Space com a Sorsa API

Para ler Spaces do X via código, use a Sorsa API, uma API e scraper do Twitter (X): o GET /spaces recebe o ID ou o link de um Space e retorna título, estado e horários, o perfil completo do host, os co-hosts e oradores e as contagens ao vivo e do replay, em uma requisição, a partir de US$ 1,40 por 1.000 Spaces. Todos os planos rodam a 20 requisições por segundo, com uma chave de API e sem conta de desenvolvedor.

1. Obtenha uma chave. Cadastre-se e copie sua chave de API no painel. Suas 100 requisições grátis consultam 100 Spaces.

2. Copie o ID do Space. O ID de um Space é o código de letras e dígitos depois de /i/spaces/ no link: em x.com/i/spaces/1yNxaYzQkPwKj, ele é 1yNxaYzQkPwKj. O X o limita a 13 caracteres, e ele não é o número longo que um post carrega.

3. Envie a requisição. Chame o GET /spaces (abre em uma nova aba) com o ID como id, ou o link inteiro como link, e a sua chave no header ApiKey.

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

4. Leia a resposta. Volta um único objeto JSON: os campos do Space no topo, creator com o perfil completo do host, participants com as pessoas por função, stats com os números do público e settings com os flags de replay e de acesso.

   {
     "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
     }
   }
   

   Ver resposta completa

A mesma chamada em Python e Node.js, pronta para um loop sobre uma lista de Spaces:

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

Um ID errado ou desconhecido retorna 404, uma chave ausente ou sem requisições retorna 403, e requisições com falha nunca são cobradas. Mais de 20 requisições por segundo retornam 429: espere um segundo e envie de novo.

#Os campos que respondem "quem" e "quantos"

A maioria dos projetos com Spaces lê cinco campos: quem é o host, quem fala, quantos ouvem ao vivo, quantos assistiram ao replay e o estado. A figura agrupa a resposta inteira pela pergunta que cada parte responde.

Se você está migrando código da API oficial do X, os campos se correspondem assim:

• Quem iniciou o Space

  Campo da Sorsa API

  creator, um perfil completo

  Campo da API oficial do X

  creator_id, um perfil só por meio de expansions

• Host e co-hosts

  Campo da Sorsa API

  admins em participants, com username e nome

  Campo da API oficial do X

  host_ids

• Oradores

  Campo da Sorsa API

  speakers em participants, com username e nome

  Campo da API oficial do X

  speaker_ids

• Tamanho do público

  Campo da Sorsa API

  total_live_listeners e total_participants em stats

  Campo da API oficial do X

  participant_count

• Visualizações do replay

  Campo da Sorsa API

  total_replay_watched em stats

  Campo da API oficial do X

  nenhum

• Agendado ou ao vivo

  Campo da Sorsa API

  state, scheduled_start

  Campo da API oficial do X

  state, scheduled_start, started_at

• Replay e clipes permitidos

  Campo da Sorsa API

  dois flags em settings

  Campo da API oficial do X

  nenhum

Um detalhe que poupa tempo de depuração: os horários em um objeto de Space são timestamps Unix (números simples), enquanto o resto da Sorsa API usa datas ISO 8601, como mostra o creator.created_at acima.

Bom saber

Trate participants.listeners como as pessoas que a sala por acaso mostra, não como uma lista de presença: o X lista só alguns ouvintes, e ouvintes sem login nunca aparecem. Para o tamanho do público, leia stats.total_live_listeners, que conta todo mundo.

Admins e oradores vêm com username, nome e um flag de verificado, enquanto o host vem com um perfil completo. Quando você precisar de seguidores e bios de todos no palco, passe os usernames deles ao GET /info-batch (abre em uma nova aba): até 100 perfis em uma requisição, a partir de US$ 0,014 por 1.000.

#Encontre Spaces para consultar: busque posts que linkam para eles

Uma consulta de Space precisa de um ID, e o lugar para achar IDs é o próprio X: os hosts anunciam seus Spaces em posts, e todo post desses carrega o link do Space. O POST /search-tweets (abre em uma nova aba) da Sorsa API com o operador filter:spaces retorna só posts que contêm um link de Space, cerca de 20 por requisição, em todo o histórico desde 2006.

Monte a consulta com os operadores que você já conhece do guia de operadores de busca do Twitter:

• from:harbor_founders_live filter:spaces encontra todo Space que um host compartilhou.
• "hardware" filter:spaces since:2026-10-01 encontra Spaces sobre um assunto de outubro em diante.
• (from:host_one_on_stage OR from:host_two_on_stage) filter:spaces acompanha uma lista curta de hosts.

O script abaixo percorre os resultados com o next_cursor, extrai os IDs de Spaces do texto e dos links de cada post e consulta cada um com a get_space() do passo anterior:

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

Cada página de busca e cada consulta é uma requisição. Cinco páginas de busca que revelam 30 Spaces custam 35 requisições no total, e a 20 requisições por segundo a execução inteira termina em poucos segundos.

#Acompanhe um Space ao vivo: número de ouvintes ao longo do tempo

Para ver como o público de um Space cresce e diminui, consulte o mesmo Space em intervalos regulares enquanto ele está ao vivo e guarde cada leitura. Cada consulta retorna o state atual, o número de ouvintes ao vivo e as pessoas no palco, então uma lista de leituras é a curva de público do 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")

Um Space de 90 minutos checado a cada 3 minutos consome 30 requisições, cerca de US$ 0,06 a US$ 1,99 por 1.000 do plano Pro. Toda requisição da Sorsa API é respondida ao vivo, então cada checagem mostra a sala como ela está naquele momento. A calculadora converte seus Spaces e checagens em requisições e no plano que as cobre:

Para alertas quando uma conta monitorada posta, inclusive o post que abre um Space, o guia de monitoramento do Twitter em tempo real mostra o loop de polling em escala, e uma Lista pública do X permite que uma requisição leia os posts mais recentes de até 5.000 hosts, como explica o guia da API de Listas do Twitter.

#Quanto custam os dados de Spaces do X: Sorsa API vs API oficial do X

Uma consulta de Space na Sorsa API custa uma requisição, seja qual for o conteúdo do Space, a partir de US$ 1,40 por 1.000 Spaces, com o perfil completo do host incluso. Na API oficial do X, o mesmo Space com o perfil do host custa US$ 0,015 a partir de 22 de novembro de 2026, ou seja, US$ 15,00 por 1.000.

Na API oficial do X, cada co-host e orador que você expande soma outros US$ 0,010, então um Space com cinco pessoas no palco custa US$ 0,055 lá; a Sorsa API retorna as mesmas pessoas na mesma requisição única. O preço é um de cinco fatores que decidem um projeto com Spaces, e a resposta da Sorsa API para cada um é um número:

• Preço por 1.000 Spaces: a partir de US$ 1,40 na Sorsa API, contra US$ 5,00 pelo Space sozinho e US$ 15,00 com o host na API oficial do X.
• Pessoas: o perfil completo do host, os co-hosts e os oradores na mesma resposta; perfis completos de todos no palco a 100 por requisição extra.
• Números do público: ouvintes ao vivo, todos os participantes e visualizações do replay, contra uma única contagem de participantes.
• Encontrar Spaces: busca com filter:spaces em posts desde 2006, então você nunca fica limitado aos links que alguém lhe enviou.
• Configuração e velocidade: uma chave de API em um header, sem conta de desenvolvedor nem OAuth, e 20 requisições por segundo em todos os planos, então 1.000 Spaces levam menos de um minuto.

A Sorsa API é somente leitura por design e nunca pede o seu login do X, então a sua própria conta do X nunca corre risco. Para criar ou comandar Spaces, use os apps do X; para postar sobre eles, combine a Sorsa API com a API oficial do X.

#Consulte seu primeiro Space

Os hosts, os oradores e o número de ouvintes de um Space do X vêm de uma única consulta pelo ID no link dele, e a API oficial do X não retorna nada depois que o Space termina. A Sorsa API lê o mesmo Space com o perfil completo do host e as contagens ao vivo e do replay em uma requisição, a partir de US$ 1,40 por 1.000 Spaces, e encontra Spaces para você pela busca. Suas 100 requisições grátis consultam 100 Spaces: cole o link de um Space na requisição acima e execute.

#FAQ