Quickstart

Quickstart guide for searching X Spaces by keyword with the Enterprise tier Spaces search endpoint, covering authentication and example requests.

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Search for Spaces
response = client.spaces.search(
    query="AI",
    space_fields=["title", "host_ids", "participant_count", "state"],
    state="live"
)

for space in response.data:
    print(f"{space.title} - {space.participant_count} participants")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Search for Spaces
const response = await client.spaces.search({
  query: "AI",
  spaceFields: ["title", "host_ids", "participant_count", "state"],
  state: "live",
});

response.data?.forEach((space) => {
  console.log(`${space.title} - ${space.participant_count} participants`);
});

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Search live Spaces only
response = client.spaces.search(query="tech", state="live")

for space in response.data:
    print(f"LIVE: {space.title}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Search live Spaces only
const response = await client.spaces.search({
  query: "tech",
  state: "live",
});

response.data?.forEach((space) => {
  console.log(`LIVE: ${space.title}`);
});

Scheduled Spaces only

cURL

shellscript

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Search scheduled Spaces only
response = client.spaces.search(query="tech", state="scheduled")

for space in response.data:
    print(f"SCHEDULED: {space.title}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Search scheduled Spaces only
const response = await client.spaces.search({
  query: "tech",
  state: "scheduled",
});

response.data?.forEach((space) => {
  console.log(`SCHEDULED: ${space.title}`);
});

---

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Search with host info
response = client.spaces.search(
    query="AI",
    space_fields=["title", "host_ids", "state"],
    expansions=["host_ids"],
    user_fields=["username", "verified"]
)

for space in response.data:
    print(f"{space.title}")
# Host info is in response.includes.users

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Search with host info
const response = await client.spaces.search({
  query: "AI",
  spaceFields: ["title", "host_ids", "state"],
  expansions: ["host_ids"],
  userFields: ["username", "verified"],
});

response.data?.forEach((space) => {
  console.log(space.title);
});
// Host info is in response.includes?.users

---

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