Quickstart

This guide walks you through retrieving Space information using the Spaces lookup endpoints.

PrerequisitesBefore you begin, you’ll need:

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

Get a Space by ID

Retrieve details for a specific Space:

cURL

curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
space.fields=title,host_ids,participant_count,scheduled_start,state,created_at" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get a Space by ID
response = client.spaces.get(
    "1DXxyRYNejbKM",
    space_fields=["title", "host_ids", "participant_count", "scheduled_start", "state", "created_at"]
)

print(f"Space: {response.data.title}")
print(f"State: {response.data.state}")
print(f"Participants: {response.data.participant_count}")

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

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

// Get a Space by ID
const response = await client.spaces.get("1DXxyRYNejbKM", {
  spaceFields: ["title", "host_ids", "participant_count", "scheduled_start", "state", "created_at"],
});

console.log(`Space: ${response.data?.title}`);
console.log(`State: ${response.data?.state}`);
console.log(`Participants: ${response.data?.participant_count}`);

Response

{
  "data": {
    "id": "1DXxyRYNejbKM",
    "state": "live",
    "title": "Discussing AI and the Future",
    "host_ids": ["2244994945"],
    "participant_count": 245,
    "created_at": "2024-01-15T09:00:00.000Z"
  }
}

Get multiple Spaces

Look up multiple Spaces at once:

cURL

curl "https://api.x.com/2/spaces?\
ids=1DXxyRYNejbKM,1YqJDqWYNQDGW&\
space.fields=title,state,participant_count" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get multiple Spaces
response = client.spaces.get_spaces(
    ids=["1DXxyRYNejbKM", "1YqJDqWYNQDGW"],
    space_fields=["title", "state", "participant_count"]
)

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

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

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

// Get multiple Spaces
const response = await client.spaces.getSpaces({
  ids: ["1DXxyRYNejbKM", "1YqJDqWYNQDGW"],
  spaceFields: ["title", "state", "participant_count"],
});

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

Get Spaces by creator

Find Spaces hosted by specific users:

cURL

curl "https://api.x.com/2/spaces/by/creator_ids?\
user_ids=2244994945,783214&\
space.fields=title,state,scheduled_start" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get Spaces by creator
response = client.spaces.get_by_creator_ids(
    user_ids=["2244994945", "783214"],
    space_fields=["title", "state", "scheduled_start"]
)

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

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

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

// Get Spaces by creator
const response = await client.spaces.getByCreatorIds({
  userIds: ["2244994945", "783214"],
  spaceFields: ["title", "state", "scheduled_start"],
});

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

Include host information

Expand host user data:

cURL

curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?\
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")

# Get Space with host info
response = client.spaces.get(
    "1DXxyRYNejbKM",
    space_fields=["title", "host_ids", "state"],
    expansions=["host_ids"],
    user_fields=["username", "verified"]
)

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

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

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

// Get Space with host info
const response = await client.spaces.get("1DXxyRYNejbKM", {
  spaceFields: ["title", "host_ids", "state"],
  expansions: ["host_ids"],
  userFields: ["username", "verified"],
});

console.log(`Space: ${response.data?.title}`);
// Host info is in response.includes?.users

Response with expansion

{
  "data": {
    "id": "1DXxyRYNejbKM",
    "state": "live",
    "title": "Discussing AI and the Future",
    "host_ids": ["2244994945"]
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "XDevelopers",
        "verified": true
      }
    ]
  }
}

Space states

State	Description
`live`	Currently active
`scheduled`	Scheduled for future
`ended`	Has ended

Available fields

Field	Description
`title`	Space title
`host_ids`	Host user IDs
`speaker_ids`	Speaker user IDs
`participant_count`	Current participants
`scheduled_start`	Scheduled start time
`started_at`	Actual start time
`ended_at`	End time
`is_ticketed`	Whether Space has tickets
`state`	Current state

Quickstart

Get a Space by ID

Response

Get multiple Spaces

Get Spaces by creator

Include host information

Response with expansion

Space states

Available fields

Next steps

Search Spaces

API Reference

​Get a Space by ID

​Response

​Get multiple Spaces

​Get Spaces by creator

​Include host information

​Response with expansion

​Space states

​Available fields

​Next steps

Search Spaces

API Reference

Get a Space by ID

Response

Get multiple Spaces

Get Spaces by creator

Include host information

Response with expansion

Space states

Available fields

Next steps