Twitter Spaces API: Titles, Hosts, Listeners as JSON

The endpoint that looks up a Space

There is one route and one required input, the Space ID, which is the token at the end of an x.com/i/spaces/<id> link. The two optional flags control how much roster and replay data comes back. Both default to true, so a plain call gives you everything X will share.

Sample response from GET /twitter/spaces/info

This is the example from our OpenAPI document, taken from a real ended Space. Timestamps are in milliseconds since the epoch, so divide by 1,000 before you hand them to most date libraries. The listeners array is empty here because the Space has ended, which is explained further down.

{
  "space": {
    "id": "1RKZzjkoYRAKB",
    "title": "TIME TO BUILD!",
    "state": "Ended",
    "content_type": "visual_audio",
    "media_key": "28_2042268179733643265",
    "created_at": 1775749652198,
    "scheduled_start": 1775840400000,
    "started_at": 1775840398722,
    "ended_at": 1775842790853,
    "updated_at": 1775842791870,
    "total_live_listeners": 264,
    "total_replay_watched": 6290,
    "is_space_available_for_replay": true,
    "is_space_available_for_clipping": true,
    "is_locked": false,
    "is_muted": false,
    "is_employee_only": false,
    "no_incognito": false,
    "disallow_join": false,
    "is_subscribed": false,
    "max_admin_capacity": 3,
    "max_guest_sessions": 10,
    "narrow_cast_space_type": 0,
    "conversation_controls": 0,
    "topics": [
      {
        "topic_id": "848920371311001600",
        "name": "Technology"
      },
      {
        "topic_id": "857879302733418496",
        "name": "Entrepreneurship"
      }
    ],
    "creator": {
      "id": "825531272621654016",
      "username": "TheBestOfAdam",
      "name": "Adam Soccolich"
    },
    "tweet": {
      "id": "2042648800989233184",
      "text": "https://t.co/TARX17sERY"
    },
    "community_id": "1471580197908586507",
    "mentioned_user_ids": [
      "1254214946751049729"
    ],
    "admins": [
      {
        "user_id": "825531272621654016",
        "screen_name": "TheBestOfAdam",
        "display_name": "Adam Soccolich",
        "avatar_url": "https://pbs.twimg.com/profile_images/...",
        "periscope_user_id": "1WLERGNWdqRQb",
        "is_verified": true,
        "is_muted_by_admin": false,
        "is_muted_by_guest": false,
        "community_role": "Moderator",
        "start": 1775840398860
      }
    ],
    "speakers": [],
    "listeners": []
  }
}

Quickstart: look up a Space

Space data is public, so a Bearer key is the only credential you need. Take the ID from a Space link, send it as id, and read the JSON. If you already have a tweet that links to a Space, the ID is the last path segment of that link.

1. Create a key at signup.
2. Copy the token after /i/spaces/ from the Space's link. It is 5 to 32 letters and digits.
3. Send the request below and read space.state to see where the Space stands.

curl "https://api.twitterapis.com/twitter/spaces/info?id=1RKZzjkoYRAKB" \
  -H "Authorization: Bearer $TWITTERAPIS_KEY"

import os
import requests

resp = requests.get(
    "https://api.twitterapis.com/twitter/spaces/info",
    headers={"Authorization": f"Bearer {os.environ['TWITTERAPIS_KEY']}"},
    params={"id": "1RKZzjkoYRAKB"},
)
resp.raise_for_status()
data = resp.json()
print(data)

const url = new URL("https://api.twitterapis.com/twitter/spaces/info");
url.search = new URLSearchParams({ id: "1RKZzjkoYRAKB" }).toString();
const resp = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TWITTERAPIS_KEY}` },
});
const data = await resp.json();
console.log(data);

What the Twitter Spaces API costs at real fill

One call returns one Space, so the fill is exactly 1 and the price does not depend on the size of the room. A Space with thousands of listeners costs the same as an empty one. The polling row shows the realistic bill for tracking a live event, where you call repeatedly to catch the roster before it disappears.

Calculated from the biller's per-call rate. The signup credit of $0.50 covers 625 lookups. See all endpoint prices.

Twitter Spaces data options compared

Spaces data is a small corner of the market, and few vendors cover it at all. What you choose depends on whether you start from an ID or need discovery, so the table separates those two jobs. A row that can search will suit a team that has no IDs yet.

Why the listener roster disappears

X does not keep the listener list after a Space ends. While the Space is running, with_listeners returns who is in the room. Once it closes, that array comes back empty whatever flag you send, and no vendor can recover it afterwards. Admins and speakers stay available, and so do the aggregate counts.

If the audience is the reason you want the data, you have to capture it live. That means finding the Space before it ends and polling on an interval while it runs, then storing each snapshot yourself. A roster taken every minute also shows you who stayed and who dropped off, which a single final count never would.

How to find Space IDs

This endpoint starts from an ID, so you need a way to get one. Hosts almost always share a link to the Space, which makes tweets the natural discovery surface. Search for posts containing spaces links with the Twitter search API, then read the token from each result.

• From a tweet. Announcement posts carry the x.com/i/spaces/<id> link in their URLs.
• From an account. Watch a host with the Twitter webhook API and catch the link the moment they post it, or follow the host from an account you run.
• From a response. The tweet object on a Space points back at the post that announced it, which helps when you start from one ID.

What this endpoint does not return

The response is metadata, not media. You get the title, the people and the counts, and you do not get the audio stream or a transcript. is_space_available_for_replay tells you whether a recording exists, and a person can open that replay in the app. If your project needs the words that were spoken, you need a separate recording and transcription step.

There is also no keyword search on this route, so it will not list every Space on a topic. That is a deliberate scope limit and the comparison table above shows who covers it. Our answer on getting Twitter Spaces data goes through the how-to in more detail.

Capture a live roster with a polling loop

The loop below polls one Space once a minute until its state reads Ended, and records who was in the room at each pass. Every snapshot goes into a dictionary keyed by handle, so at the end you have the first and last minute each listener was seen, which gives you an attendance curve that no single response can show. The handles sit on screen_name inside each roster entry.

Start the loop before the Space does if you can. A Space that is still scheduled returns its scheduled_start, so a job can sleep until then and begin polling on time. To catch a host's next Space without watching by hand, register that account with the Twitter webhook API and start the loop when the announcement arrives. Our monitoring page describes how that watching works in more detail.

import os
import time
import requests

API = "https://api.twitterapis.com/twitter/spaces/info"
HEADERS = {"Authorization": f"Bearer {os.environ['TWITTERAPIS_KEY']}"}

space_id = "1RKZzjkoYRAKB"
seen = {}
minute = 0

while True:
    resp = requests.get(API, headers=HEADERS, params={"id": space_id}, timeout=30)
    resp.raise_for_status()
    space = resp.json()["space"]

    if space["state"] == "Ended":
        break

    for person in space["listeners"]:
        handle = person["screen_name"]
        first, _ = seen.get(handle, (minute, minute))
        seen[handle] = (first, minute)

    minute += 1
    time.sleep(60)

print(len(seen), "listeners seen")

What teams do with Spaces data

Spaces leave little behind once they end, so most uses revolve around recording a moment that would otherwise vanish. The title, the host and the headline counts survive, and they are enough for reporting. The roster is what makes the richer jobs possible, and it only exists while the Space runs. These are the jobs the endpoint is usually asked to do.

Enrich what you collect with the rest of the API. A handle from the roster goes straight into the user API for a bio and a follower count, and the followers API shows who those people reach. For a recurring community call, save a Twitter list of regular speakers and watch how it changes over time.

• Event reporting. Send sponsors the live count, replay views and duration, all from one response.
• Speaker research. Pull admins and speakers from past Spaces in your field to build a guest shortlist.
• Audience capture. Sample the live roster to see who attends, then compare across a series.
• Community tracking. community_id links a Space to its X Community, and topics gives you X's own labels for grouping.

Reading the less obvious fields

A few fields answer questions people usually assume they cannot ask. content_type reads audio for an audio-only Space and visual_audio when the host turned video on. started_at minus scheduled_start tells you how late it began, and ended_at minus started_at gives the running time, all in milliseconds. A scheduled Space that has not begun returns started_at as 0.

tweet points at the post that wraps the Space, which you can pass to a tweet by ID lookup for its engagement. mentioned_user_ids lists accounts the Space tagged, and the roster entries carry is_verified and a community_role. If you have not called the API before, the quickstart and the rate limits page cover the basics that apply to every route.

Handling scheduled, cancelled and missing Spaces

A Space ID can resolve to nothing, and your code should expect that. The response is a 404 with space null when the ID resolves to no Space, which usually means a typo or a Space that was removed, so log it and move on rather than retrying. A Space that is planned but has not begun returns started_at as 0, so test that field before you compute a duration.

Read Spaces from an AI agent

Hand an agent a Space link and it can report who hosted, what it covered and how many people listened. The tool below takes the same inputs as the REST call, and the MCP page shows how to connect it to your client with the same key.

• twitter_spaces_info calls GET /twitter/spaces/info

npx -y @twitterapis/mcp@latest