Quickstart

Quickstart guide for searching X Spaces by keyword with the X API v2 standard tier Spaces search endpoint, covering authentication and example calls.

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