Twitter (X) Spaces API: Official Endpoints, Space Details and Real Listener Data

By TwitterAPI.io Team•12 min read
Diagram comparing X API v2 Spaces endpoints with the TwitterAPI.io spaces detail endpoint: paths, auth, fields and price per Space
Two ways to read a Space: X API v2 endpoints on the left, TwitterAPI.io /twitter/spaces/detail on the right.
TL;DR
  • Official X endpoints: /2/spaces/:id, /2/spaces, /2/spaces/by/creator_ids, /2/spaces/search, /2/spaces/:id/tweets, /2/spaces/:id/buyers; 300 requests per 15 minutes each; $0.005 per Space read.
  • TwitterAPI.io: one call, GET /twitter/spaces/detail?space_id=, X-API-Key header, no X account needed, 30 credits ($0.0003) per Space detail: about 1/16 of X's per-Space rate.
  • Ended Spaces still resolve: all 110 IDs in our sample returned a full object, 49 of them with state: "Ended"; X's docs say ended Spaces are no longer available through its endpoints.
  • Listener counts: median stats.total_live_listeners was 4 for running Spaces and 191 for ended ones; 20 of 49 ended Spaces passed 1,000.
  • Real state values: Running, Ended, TimedOut, NotStarted. The docs example says Live, but live Spaces came back as Running, so match on the value the API actually returns.
  • No Spaces search on our side: find IDs by searching posts that link x.com/i/spaces with /twitter/tweet/advanced_search, then call the detail endpoint per ID.

Spaces are X's live audio rooms. Developers usually want three things from them: find Spaces on a topic or by a host, read a Space's state and audience while it runs, and keep the numbers after it ends for a report. The official X API covers the first two while a Space is live; the third is where most projects get stuck.

This page is the endpoint reference for Spaces data: what each official /2/spaces endpoint does, what TwitterAPI.io's /twitter/spaces/detail returns field by field (checked against a real response, not just the docs), what both cost, and a study of 110 real Spaces. It is narrower than our overview of all Twitter API endpoints, and it is not about Communities or streaming: for those see the sibling guides linked at the end. It does not cover downloading Space audio.

Ended Spaces still returned by /twitter/spaces/detail in our sample

49 of 49 ended Spaces (of 110 total) returned full stats

01 — Section

What the official X API v2 Spaces endpoints do

X groups its Spaces endpoints into lookup and search. Every path below is on api.x.com and was checked on docs.x.com for this guide.

EndpointWhat it returnsAuth
GET /2/spaces/:idOne Space by IDBearer or OAuth 2.0 user
GET /2/spaces?ids=1 to 100 Spaces by IDBearer or OAuth 2.0 user
GET /2/spaces/by/creator_idsSpaces created by 1 to 100 user IDsBearer or OAuth 2.0 user
GET /2/spaces/searchSpaces matching a keyword, state=live, scheduled or allBearer or OAuth 2.0 user
GET /2/spaces/:id/tweetsPosts shared in the SpaceBearer or OAuth 2.0 user
GET /2/spaces/:id/buyersUsers who bought a ticketOAuth 2.0 user only

Fields. A Space object is sparse by default. Ask for more with space.fields: created_at, ended_at, id, is_ticketed, lang, participant_count, scheduled_start, started_at, state, subscriber_count, title, updated_at. Expansions turn creator_id, host_ids, invited_user_ids, speaker_ids and topic_ids into user or topic objects.

Roles and counts. X's Spaces introduction describes one creator (the primary host), co-hosts, and speakers, with up to 10 speakers including hosts. Listeners are not listed individually: you get an aggregate participant_count.

Lifecycle. Spaces can be scheduled up to 14 days ahead. X's docs state that Spaces are accessible while they are live and that once ended they are no longer available for retrieval: the endpoints return an error. That one sentence decides most designs. If you need numbers after the end, you must have polled while the Space was running.

Rate limits. The rate-limit table on docs.x.com lists 300 requests per 15 minutes per app and per user for each Spaces endpoint; /2/spaces/by/creator_ids adds 1 request per second.

02 — Section

Official Spaces pricing on X's pay-per-usage rate card

X's API is billed per resource on its pay-per-usage rate card (docs.x.com/x-api/getting-started/pricing). The Spaces row reads "Space: Read, $0.005 per resource". Post reads are $0.005 each and user reads $0.010 each, so the posts from /2/spaces/:id/tweets and any expanded host or speaker user objects are billed on top of the Space itself. Pay-per-usage plans are capped at 3 million post reads per monthly billing cycle; Enterprise sits above that.

A minimal request looks like this. It works with an app-only bearer token from the X developer console:

python
# X API v2 (official): look up Spaces by ID with an app-only bearer token.
# Billed on X's pay-per-usage rate card at $0.005 per Space read.
import requests

BEARER = "YOUR_X_BEARER_TOKEN"
r = requests.get(
    "https://api.x.com/2/spaces",
    headers={"Authorization": f"Bearer {BEARER}"},
    params={
        "ids": "1abcDEFghIJkl",
        "space.fields": "state,title,participant_count,started_at,ended_at,speaker_ids",
        "expansions": "creator_id,speaker_ids",
    },
    timeout=30,
)
print(r.status_code, r.json())
03 — Section

TwitterAPI.io /twitter/spaces/detail: request and real response

TwitterAPI.io has one Spaces endpoint: GET https://api.twitterapi.io/twitter/spaces/detail with a required space_id query parameter and your key in the X-API-Key header. No X account, developer app or OAuth flow is needed for reads. The Space ID is the last path segment of a Space link, for example x.com/i/spaces/1abcDEFghIJkl.

We called it more than 100 times for this guide and read the fields straight from the responses. A successful body is {"status": "success", "msg": ..., "data": {"space": {...}}}. Note the extra space level under data: the reference page describes data as the Space object itself, but every real response we received nested it one level deeper.

FieldTypeWhat we saw
id, title, media_keystringPresent on all 110
statestringRunning, Ended, TimedOut, NotStarted
created_at, updated_at, scheduled_startISO 8601 string or nullscheduled_start set on 12 of 110
statsobjecttotal_live_listeners, total_participants, total_replay_watched
settingsobjectreplay, clipping, locked, muted flags; max_guest_sessions
creatorobject22 keys; only id was filled on every Space
participantsobjectadmins[], speakers[], listeners[]

Participant entries. Each entry in admins, speakers and listeners carries userName, name, profilePicture, isBlueVerified and a participant_info object (periscope_user_id, start_time, is_muted_by_admin, is_muted_by_guest). The admins list is where the host's handle is: in our sample the creator object had all 22 profile keys, but followers, userName and the rest came back empty; only id (110 of 110) and isBlueVerified (54) were filled. To get the host's follower count, pass the admin's userName to /twitter/user/info.

Errors. A made-up space_id returned HTTP 404. The reference page also documents HTTP 400 with error and message for a bad request.

Price. 30 credits per Space detail returned, which is $0.0003 (100,000 credits = $1). Against X's $0.005 per Space read that is about 1/16 of the official rate for the Space object alone. For the posts around a Space, our tweet endpoints are $0.15 per 1,000 tweets returned vs X's $5 per 1,000 post reads ($0.005 each): about 33x apart on the two published rate cards.

04 — Section

Finding Space IDs without a Spaces search endpoint

TwitterAPI.io has no Spaces search endpoint. The working route is the one people already use to share Spaces: posts that link them. A Space link always contains /i/spaces/<id>, and /twitter/tweet/advanced_search returns each link in entities.urls[].expanded_url.

We tested three queries. A quoted url:"x.com/i/spaces" operator returned zero posts. The bare x.com/i/spaces, the quoted "i/spaces", and spaces url:spaces each returned a full page of 20 posts, all with a Space link. Add keywords or from: operators to narrow it, for example x.com/i/spaces from:NASA or x.com/i/spaces bitcoin.

In the study, 11 search pages returned 220 posts and 167 distinct Space IDs: hosts and their audiences tend to post a link once, so duplicates were rare. With search at $0.15 per 1,000 tweets returned, discovery is the small part of the bill.

Trade-off vs /2/spaces/search. X's search matches Space titles and can filter by state=live or scheduled. Link-based discovery only sees Spaces someone posted about, which skews toward Spaces that wanted an audience. It does see ended Spaces, which X's search does not return.

05 — Section

What 110 real Spaces looked like: states and listeners

We fed 110 of the discovered IDs into /twitter/spaces/detail and recorded each response once. Every call returned a Space object; none failed.

StateSpacesShareMedian live listeners
Running5852.7%4
Ended4944.5%191
TimedOut21.8%n/a
NotStarted10.9%n/a

Running Spaces are mostly small. Half of the 58 running Spaces had 4 or fewer live listeners, and 29 sat between 1 and 9. A handful were large: the 90th percentile was 1,109 and the largest reported 166,085.

Ended Spaces are the ones people linked to after the fact. The median ended Space reported 191 live listeners and 20 of 49 passed 1,000 (maximum 78,437). That fits how links spread: a big Space gets shared and reshared after it ends, so link-based discovery over-samples popular ended Spaces.

Replays. 57.1% of ended Spaces had is_space_available_for_replay: true. The median total_replay_watched for ended Spaces was 0, the 90th percentile 537, and the maximum 29,932. For running Spaces it was always 0.

Bar charts: state of 110 Spaces from the spaces detail endpoint and live listener bands for running vs ended Spaces
110 Spaces found through public posts and read with /twitter/spaces/detail; snapshot per Space at request time. Collected in 2026.
06 — Section

How the response changes when a Space ends

Comparing running and ended Spaces side by side shows which fields are live counters and which become a final record. These patterns are what we observed in the sample; the reference docs do not describe them, so treat them as behavior to test, not a contract.

FieldRunning (median / max)Ended (median / max)
participants.speakers entries1 / 107 / 117
participants.listeners entries1 / 500 / 1
stats.total_participants4 / 5520 / 1
stats.total_live_listeners4 / 166,085191 / 78,437

Listener list is a sample, capped at 50. While a Space runs, listeners[] never held more than 50 entries; 7 running Spaces hit exactly 50 while their listener stats were higher. Use stats for audience size and treat listeners[] as a partial list.

After the end, listeners and current participants empty out. Ended Spaces returned an empty listeners[] and total_participants of 0 (one exception had 1), while total_live_listeners kept its final value. If you need the room's peak, read total_live_listeners, not total_participants.

The speakers list grows past X's 10-speaker limit. On ended Spaces the median speakers[] length was 7 and 18 of 49 listed more than 10 (up to 117). X's docs cap speakers at 10 at any moment, so our reading is that an ended Space lists everyone who held a speaker slot during the session. That makes it useful for "who spoke" reports.

Duration. The response has no started_at or ended_at. For ended Spaces, updated_at is the last state change, so updated_at - created_at approximates how long the Space ran (it includes any scheduled wait). By that measure the median ended Space ran 94.8 minutes; 13 ended within 30 minutes and 12 ran longer than 4 hours.

Bar charts: number of speakers listed for running vs ended Spaces, and created_at to updated_at spans for ended Spaces
58 running and 49 ended Spaces from /twitter/spaces/detail. updated_at used as an end-time proxy. Collected in 2026.
07 — Section

Runnable Python: monitor a Space until it ends

Because ended Spaces still resolve on our endpoint, you do not have to poll aggressively to keep the final numbers. A slow poll is enough to catch the transition from Running to Ended (or TimedOut) and store the final stats.

Cost of this loop. One poll every 2 minutes is 30 detail calls an hour, $0.009 an hour for a running Space at 30 credits each. A 95-minute Space (our median) costs about $0.015 to watch end to end.

Handle the odd states. TimedOut appeared on 2 of 110 Spaces and NotStarted on 1. Treat any value other than Running as terminal for a watcher, but re-check NotStarted Spaces near their scheduled_start, because they move to Running when the host goes live. On HTTP 429 or a 5xx, back off and retry the same space_id; on 404, drop the ID, since it was never a valid Space.

What to store. For a report, keep the last Running snapshot and the first Ended snapshot: the first gives you the live room (listener sample, current speakers), the second gives the final total_live_listeners, the full speakers list and, if replay is on, a total_replay_watched you can refresh later to measure replay audience.

Picking up new Spaces. Combine it with the discovery function from the full example below: run a link search every few minutes for your hosts or keywords, keep a set of IDs you have seen, and start a watcher for each new Running ID. A search that finds nothing costs the 15-credit minimum, $0.00015.

python
import time
import requests

BASE = "https://api.twitterapi.io"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}


def watch(space_id, every=120):
    """Poll one Space until it leaves the Running state; print listener counts."""
    while True:
        r = requests.get(f"{BASE}/twitter/spaces/detail", headers=HEADERS,
                         params={"space_id": space_id}, timeout=30)
        if r.status_code == 404:
            print("unknown space_id")
            return
        sp = (r.json().get("data") or {}).get("space") or {}
        stats = sp.get("stats") or {}
        print(sp.get("state"), stats.get("total_live_listeners"),
              stats.get("total_participants"))
        if sp.get("state") != "Running":
            return sp  # Ended, TimedOut or NotStarted
        time.sleep(every)
08 — Section

Official API or TwitterAPI.io: which one fits your Spaces project

NeedX API v2TwitterAPI.io
Find live Spaces by title keyword/2/spaces/searchLink search via advanced_search
Spaces by a list of hosts/2/spaces/by/creator_idsfrom: + x.com/i/spaces search
Data after the Space endsNot available per X docsReturned (49 of 49 in our sample)
Who spoke, with handlesspeaker_ids expansion (user reads extra)participants.speakers[] in one call
Ticket buyers/2/spaces/:id/buyers (user OAuth)Not offered
Price per Space object$0.005$0.0003

Field mapping. If you are porting code from X's API, these are the closest equivalents we found in the real responses:

X API v2 field/twitter/spaces/detail field
state (live, scheduled, ended)state (Running, NotStarted, Ended, TimedOut)
participant_countstats.total_participants (live) or stats.total_live_listeners
creator_id, host_idscreator.id, participants.admins[]
speaker_idsparticipants.speakers[] (with userName)
started_at, ended_atnot returned; created_at, updated_at
scheduled_start, titlescheduled_start, title

There is no direct equivalent of is_ticketed, lang, subscriber_count or topics in the detail response, and X's API has no equivalent of the replay counters. Keep both sets of names in one adapter function rather than spreading them through your code: the state strings in particular differ in spelling and case.

Choose X's API if you need title search with state=scheduled, ticket buyers, or you are building a product under X's developer agreement that must use first-party access. X's Spaces docs also ask apps to remove Spaces data that is no longer available on the platform.

Choose TwitterAPI.io if you want ended Spaces, speaker handles and replay counts in a single call, need no OAuth setup, or are processing many Spaces where the per-Space rate matters. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days), which covers more than 3,000 Space detail calls. Rate limits start at 0.2 requests per second before the first payment and rise to 20 once paid.

09 — Section

How we collected this

Question. What does /twitter/spaces/detail return for real Spaces, and how do states, listener counts, participant lists and timing differ between running and ended Spaces?

Sample. /twitter/tweet/advanced_search with x.com/i/spaces (Latest and Top) and "i/spaces" (Latest), 11 pages, 220 posts, 167 distinct Space IDs. We read 110 of them with /twitter/spaces/detail, one call each, plus one call with a made-up ID to record the error. 127 requests in total, about $0.08 at list prices. Collected in 2026.

Window. Each Space is a single snapshot at the moment of the call. Latest search favors Spaces linked in the hours before collection; Top search favors popular ones.

What the sample cannot show. It only sees Spaces someone linked in a public post, so quiet Spaces with no shared link are missing and popular ended Spaces are over-represented. It is not a census of all Spaces. Duration is an approximation from updated_at. Behavior such as the 50-entry listener list is what we observed, not documented.

Privacy. Hosts and listeners can be private individuals, so we publish aggregates only. No Space IDs from the sample, titles, handles or names are stored in the study files; raw responses stayed on the collection machine. The per-Space rows in the study folder hold only state, counts, booleans and time spans.

python
import re
import requests

API_KEY = "YOUR_API_KEY"  # from the TwitterAPI.io dashboard
BASE = "https://api.twitterapi.io"
HEADERS = {"X-API-Key": API_KEY}
SPACE_RE = re.compile(r"/i/spaces/([A-Za-z0-9]+)")


def find_space_ids(query="x.com/i/spaces", pages=3):
    """Collect Space IDs from public posts that link a Space."""
    ids, cursor = [], ""
    for _ in range(pages):
        params = {"query": query, "queryType": "Latest"}
        if cursor:
            params["cursor"] = cursor
        r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
                         headers=HEADERS, params=params, timeout=30)
        r.raise_for_status()
        body = r.json()
        for tweet in body.get("tweets", []):
            for u in (tweet.get("entities") or {}).get("urls", []):
                m = SPACE_RE.search(u.get("expanded_url") or "")
                if m and m.group(1) not in ids:
                    ids.append(m.group(1))
        if not body.get("has_next_page"):
            break
        cursor = body.get("next_cursor") or ""
    return ids


def space_detail(space_id):
    """Return data.space, or None if the ID is unknown (HTTP 404)."""
    r = requests.get(f"{BASE}/twitter/spaces/detail",
                     headers=HEADERS, params={"space_id": space_id}, timeout=30)
    if r.status_code == 404:
        return None
    r.raise_for_status()
    body = r.json()
    if body.get("status") != "success":
        print("error:", body)
        return None
    return (body.get("data") or {}).get("space")


if __name__ == "__main__":
    for sid in find_space_ids(pages=2)[:10]:
        sp = space_detail(sid)
        if not sp:
            continue
        stats = sp.get("stats") or {}
        part = sp.get("participants") or {}
        hosts = [a.get("userName") for a in part.get("admins") or []]
        print(sid, sp.get("state"), "| live listeners:", stats.get("total_live_listeners"),
              "| speakers:", len(part.get("speakers") or []),
              "| hosts:", hosts,
              "| replay:", (sp.get("settings") or {}).get("is_space_available_for_replay"))

Researching this?Free starter credits cover end-to-end testing — Google sign-in, no card. Get a key.

10 — Questions

Questions readers ask

Does the X API have a Spaces endpoint?

Yes. X API v2 has six: GET /2/spaces/:id, GET /2/spaces (up to 100 IDs), GET /2/spaces/by/creator_ids, GET /2/spaces/search, GET /2/spaces/:id/tweets and GET /2/spaces/:id/buyers. They are read-only, accept an app-only bearer token (buyers needs an OAuth 2.0 user token with space.read), and are billed at $0.005 per Space read on X's pay-per-usage rate card.

Can I get data for a Space that has already ended?

Not from X's official endpoints: X's docs say Spaces are no longer available for retrieval once they end. TwitterAPI.io's /twitter/spaces/detail returned all 49 ended Spaces in our sample, with final total_live_listeners, total_replay_watched and the speakers list.

How do I get a Twitter Space ID?

It is the last segment of the Space link: in x.com/i/spaces/1abcDEFghIJkl the ID is 1abcDEFghIJkl. To find IDs in bulk, search posts for x.com/i/spaces with /twitter/tweet/advanced_search and read entities.urls[].expanded_url, or use X's /2/spaces/search for live and scheduled Spaces.

Does the Spaces API return the list of listeners?

X's API returns only an aggregate participant_count. TwitterAPI.io returns a listeners[] array while the Space runs, but in our sample it never held more than 50 entries and was empty after the Space ended. Use stats.total_live_listeners for audience size.

What does the state field mean in /twitter/spaces/detail?

We saw four values: Running (live now), Ended, TimedOut and NotStarted (scheduled). The reference page uses Live as an example, but live Spaces came back as Running, so compare against Running in code.

How much does the Twitter Spaces API cost?

On X's pay-per-usage rate card a Space read is $0.005, with posts at $0.005 and users at $0.010 each when you expand them. On TwitterAPI.io a Space detail is 30 credits, $0.0003, and tweets are $0.15 per 1,000 returned. See the pricing page for plans.

Can I download the audio of a Space with the API?

Neither API documents an audio download. X's endpoints return metadata only. TwitterAPI.io returns media_key and replay flags such as is_space_available_for_replay, not an audio file.

What are the rate limits for Spaces endpoints?

X lists 300 requests per 15 minutes per app and per user for each Spaces endpoint, plus 1 request per second on /2/spaces/by/creator_ids. TwitterAPI.io limits are per account: 0.2 requests per second before the first payment, 20 once paid, 50 on Scale and 500 on Business.

11 — Further reading

Continue

Sources & further reading
More from this series

Writing about something you built with TwitterAPI.io? Our community rewards program pays API credits for honest tutorials, build logs and videos.

Build it

Stop reading. Start building.

Starter credits cover real testing on real data. Google sign-in, no card, no application queue.

Get an API key

Already building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.