Quickstart

Search for Spaces by keyword

This guide walks you through searching for Spaces by keyword.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• Your App’s Bearer Token

---

Search for Spaces

Search for Spaces matching a keyword:

cURL

shellscript

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"

Response

{
  "data": [
    {
      "id": "1DXxyRYNejbKM",
      "state": "live",
      "title": "Discussing AI and the Future",
      "host_ids": ["2244994945"],
      "participant_count": 245
    },
    {
      "id": "1YqJDqWYNQDGW",
      "state": "live",
      "title": "AI in Healthcare",
      "host_ids": ["783214"],
      "participant_count": 89
    }
  ],
  "meta": {
    "result_count": 2
  }
}

---

Filter by state

Search only live or scheduled Spaces:

Live Spaces only

cURL

shellscript

curl "https://api.x.com/2/spaces/search?query=tech&state=live" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Scheduled Spaces only

cURL

shellscript

curl "https://api.x.com/2/spaces/search?query=tech&state=scheduled" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

Include host information

Expand host user data:

cURL

shellscript

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

---

Common parameters

Parameter	Description
query	Search query (required)
state	Filter: live, scheduled, or all
max_results	Results to return (1-100)
space.fields	Space fields to include
expansions	Related objects to include
user.fields	User fields to include

---

Next steps

Space lookup

Look up Spaces by ID

API Reference

Full endpoint documentation