Quickstart

This guide walks you through retrieving Space information using the Spaces lookup endpoints. Reference for the X API v2 standard tier covering lookup.

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

Prerequisites

Before 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

shellscript

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

shellscript

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

shellscript

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

shellscript

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

---

Next steps

Search Spaces

Find Spaces by keyword

API Reference

Full endpoint documentation