Quickstart

Retrieve Space details by ID or creator

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"

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"

---

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"

---

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"

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