X API Spaces: the field every example gets wrong

#Quick answer

The X API Spaces namespace has six endpoints, all of them GETs, and the single most copied line in its documentation does not work. space.fields=host_ids appears in X's own quickstart, in the lookup guide, and in both SDK samples, but host_ids is not in the space.fields enum at API version 2.174. Hosts and speakers are expansions. That distinction is free today and starts costing $0.010 per user on 22 November 2026.

Last updated: November 2026

Three facts shape everything you can build here. The namespace is read-only. Ended Spaces disappear. And the identities you actually want are not fields.

#Six endpoints, and what each one hands back

Spaces on X (formerly Twitter) are live audio rooms. If you want the product rather than the API, we have a separate walkthrough of how to use X Spaces. The API surface is smaller than the product by a long way.

Two things in that table are worth pausing on.

max_results defaults to 100 on search, on buyers and on shared Posts. Most v2 endpoints default to 10. So GET /2/spaces/:id/buyers with no parameters is a request to bill up to one dollar, and GET /2/spaces/search?query=ai with no parameters is up to fifty cents. The defaults are the maximums.

And there is no Spaces row on the Owned Reads table in X API pricing. Bookmarks, lists, likes, followers and your own Posts all drop to $0.001 when you read your own data through your own app. Spaces do not. Reading the Space you hosted yourself costs the same $0.005 as reading a stranger's.

#host_ids is not a space.field

Here is X's Spaces search quickstart, verbatim:

curl "https://api.x.com/2/spaces/search?query=AI&\
space.fields=title,host_ids,participant_count,state&state=live" \
  -H "Authorization: Bearer $BEARER_TOKEN"

And here is the complete space.fields enum from the live OpenAPI description at api.x.com/2/openapi.json, version 2.174:

created_at, ended_at, id, is_ticketed, lang, participant_count,
scheduled_start, started_at, state, subscriber_count, title, updated_at

Twelve values. No host_ids. No creator_id, speaker_ids, invited_user_ids or topic_ids either. Those five are the expansions enum, which is a different parameter.

This is not a stale sample that the SDKs have quietly corrected. Download xdk 0.10.6, X's own Python SDK, and xdk/spaces/client.py types space_fields as a Literal of exactly those twelve strings, with host_ids appearing only in the expansions literal. The official SDK's type checker rejects the call the official quickstart tells you to make. The lookup guide's "Response fields" table repeats the same mistake, listing host_ids and speaker_ids as fields to request.

Ask for expansions instead:

curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
space.fields=title,participant_count,state,started_at&\
expansions=creator_id,host_ids,speaker_ids&\
user.fields=username,name" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Two smaller gaps sit next to this one. The Fields page, whose entire job is to list every *.fields parameter, has rows for Posts, Users, Media, Polls and Places and no row for space.fields. The Expansions page lists four Space expansions and omits topic_ids. And the Spaces introduction links four times to a "Spaces data dictionary" at data-dictionary/reference#space - an anchor that does not exist on that page, which contains example Post payloads and nothing about Spaces. The OpenAPI description is the only authoritative field list, which is exactly the pattern we hit in the X API bookmarks namespace.

#On 22 November, the identities start billing

Expansion objects are free right now. They stop being free on 22 November 2026, at Post $0.005, User $0.010, and Media, Poll and Place $0.005 each. The detail is in our write-up of X API expansions.

Put that next to the section above and the arithmetic changes shape. Because host and speaker identities are reachable only through expansions, there is no unpaid path to them after 22 November. A single Space lookup that resolves a creator, two co-hosts and eight speakers goes from $0.005 to $0.005 plus eleven User reads, or $0.115. Deduplication is per 24-hour UTC window, so polling the same Space every 60 seconds for a two-hour show pays for those users once, not 120 times, but a discovery crawl across 100 distinct Spaces pays for every distinct participant.

topic_ids is the odd one out. Topics are not on the read rate card at all, and they were not in the expansion pricing list either, so an expansions=topic_ids request currently has no published price.

#Spaces search is a substring match, not a query language

query on /2/spaces/search accepts up to 2,048 characters. It does almost nothing with them.

X staff answered this plainly on 20 November 2024, to a developer who could not understand why query=MAGA OR politics returned zero results while each word alone returned seven and eight: the endpoint "performs exact case-insensitive match of the specified search term," search operators "aren't supported like they are with the Search Tweets endpoints," and "if you want to make multiple queries, you will need to make separate requests for each."

So the practical shape of Spaces search is:

• One literal, case-insensitive substring, matched against the Space title only. Not the host's bio, not the description, not what is being said.
• state accepts live, scheduled or all. There is no ended.
• max_results caps at 100 and there is no pagination_token. Result 101 is unreachable. Permanently.
• Every synonym you want is another request at up to $0.50.

A keyword-monitoring product therefore costs a multiple of what the docs imply. Ten tracked terms polled every five minutes is 2,880 requests a day, which fits inside 300 per 15 minutes but not inside most budgets.

#Ended Spaces are unretrievable, and that breaks two endpoints

X documents this in one sentence on the introduction page: once a Space ends it "will no longer be available for retrieval using the Spaces endpoints." The forum shows what it feels like. A developer in August 2025 queried /2/spaces/by/creator_ids for an account that had definitely hosted Spaces and got meta.result_count: 0; looking the Space up by its own ID returned Not Found. A separate October 2025 report drew the same answer from X staff three days later: no Spaces for that user ID.

Follow that through to the two paginated endpoints. /2/spaces/:id/buyers and /2/spaces/:id/tweets are post-mortem tools by nature - you want them when the show is over. They are only callable while the Space is live. Retrospective Spaces analytics is not a thing you can build on this namespace.

The state field is also looser than it looks. The lookup guide documents three states including ended, and a developer reported back in October 2021 that ended exists but is only visible through lookup by ID. The 2.174 schema resolved this by giving state no enum at all: it is a bare string. Do not switch on it exhaustively.

#The webhook is the only trigger that works

Spaces got exactly three changelog entries in five years: the August 2021 launch, the November 2021 addition of ticket buyers and Topics, and then nothing until 28 January 2026, when spaces.start and spaces.end arrived in the X Activity API at $0.005 per delivered event.

That third entry is the one that makes the namespace usable. You subscribe by User ID, get a push the moment a tracked account goes live, and then you have a window in which lookup, buyers and shared Posts all still answer. Poll-and-hope cannot work against a resource that deletes itself.

Note the gap in that list. February 2022 brought /2/spaces/:id/tweets with no changelog entry at all. It appeared in a forum announcement, along with subscriber_count, which counts people who set a reminder for a scheduled Space and - per that same announcement - "is only available to the creator of the Space," requiring OAuth 2.0 with space.read granted by that creator. The field sits in the public enum today with no note attached.

#What the namespace still cannot do

• Create or control a Space. All six endpoints are GETs. No scheduling, no starting, no ending, no promoting a listener to speaker, no muting.
• Identify listeners. participant_count is an aggregate that includes the hosts. X staff, February 2022: individual attendance is "not included," and an OAuth app cannot see whether a user joined. Still true at 2.174.
• Find Spaces a user is speaking in. Only by/creator_ids exists, so you can find Spaces someone hosted, never ones they joined as a speaker. A 2022 request for this went to the open-evolution repo and never shipped.
• Read ticket data in practice. /2/spaces/:id/buyers is the only Spaces endpoint with no app-only Bearer option, OAuth 2.0 user context only, and its externalDocs still points at the dead developer.twitter.com. X paused Ticketed Spaces in October 2022 and the developer changelog has never mentioned the product again.

One more oddity worth knowing before you plan a build: the rate-limits page lists GET /2/users/:id/following/spaces at 300/15min in its Users block. That path has no reference page, no mention in the Spaces namespace, and does not exist in the 2.174 description. Treat it as a ghost row, not a roadmap.

It is telling that the most serious Spaces tool in the forum right now does not use these endpoints at all. On 4 November 2026 a developer requested Public Utility access for a live Spaces reply viewer built on GET /2/tweets/search/stream and /2/tweets/search/recent, estimating $510 to $560 a month in reads. Spaces tooling in 2026 is still built out of Post search.

#If what you actually wanted was reach

Most people who find this page are trying to turn Spaces into growth, and run into the fact that the API cannot see listeners, cannot see replays, and cannot see anything once the room closes. The part of the loop that does respond to automation is the Post and reply layer around a Space - the announcement, the live quote-posts, the recap thread.

That is what X-Autopilot does, and it does it from your own Mac in your own logged-in browser session rather than from a shared cloud IP pool, which is a smaller detection surface than a hosted scheduler, not a guarantee of anything. Browser automation of engagement on X is a gray area and we will not tell you otherwise: the API route is the sanctioned one, and X's Automation Rules are the document that governs the rest. Read them before you point any tool at an account you care about.