TwittrAPI LogoTwittrAPI
Docs
Spaces & Audio

Spaces & Audio

Access Twitter Spaces data including live and recorded audio rooms, participants, hosts, and recordings.

Overview

The Spaces endpoints provide comprehensive access to Twitter Spaces - live and scheduled audio conversations. You can retrieve Space details, search for Spaces, get participant lists, access recordings, and monitor live Spaces. These endpoints are essential for building applications that interact with Twitter's audio content.

Key Features

  • Space Lookup: Get detailed information about any Space
  • Live Spaces: Find currently live Spaces
  • Scheduled Spaces: Discover upcoming Spaces
  • Participant Management: Get hosts, speakers, and listeners
  • Search: Search Spaces by topic, title, or host
  • Recordings: Access Space recordings and playback URLs
  • User Spaces: Get all Spaces for a specific user
  • Real-Time Data: Access live participant counts and status

Authentication

All endpoints require authentication via the X-API-KEY header:

X-API-KEY: YOUR_API_KEY

For detailed authentication information, see our Authentication Guide.

Understanding Space States

Spaces can be in different states throughout their lifecycle. Understanding these states is crucial for building robust applications.

Space States

StateDescriptionCharacteristics
scheduledSpace is scheduled but not yet startedHas scheduled_start time, state: "scheduled"
liveSpace is currently runningHas started_at time, state: "live", real-time participant count
endedSpace has finishedHas ended_at time, state: "ended", may have recording
cancelledSpace was cancelled before startingstate: "cancelled", no recording available

State Transitions

scheduled → live → ended
     ↓
cancelled

Working with States

function getSpaceStatus(space) {
  switch (space.state) {
    case 'scheduled':
      return {
        status: 'Upcoming',
        time: space.scheduled_start,
        canJoin: false
      };
    case 'live':
      return {
        status: 'Live Now',
        participants: space.participant_count,
        canJoin: true
      };
    case 'ended':
      return {
        status: 'Ended',
        endedAt: space.ended_at,
        hasRecording: space.recording_available
      };
    case 'cancelled':
      return {
        status: 'Cancelled',
        canJoin: false
      };
  }
}

Endpoints

Get Space by ID

Retrieves detailed information about a specific Space, including its current state, participants, host information, and metadata.

Endpoint: GET /space/{space_id}

Path Parameters

NameTypeRequiredDescription
space_idstringYesThe unique Space ID (e.g., "1abcdefghijklmno")

Request Examples

curl --request GET \
  --url 'https://<direct.gateway>/space/1abcdefghijklmno' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

const response = await fetch('https://<direct.gateway>/space/1abcdefghijklmno', {
  headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const space = await response.json();

Python:

import requests
 
response = requests.get(
    'https://<direct.gateway>/space/1abcdefghijklmno',
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
space = response.json()

Response Example

{
  "id": "1abcdefghijklmno",
  "state": "live",
  "title": "Tech Talk: The Future of AI",
  "created_at": "2024-10-01T12:00:00.000Z",
  "started_at": "2024-10-01T12:05:00.000Z",
  "scheduled_start": "2024-10-01T12:00:00.000Z",
  "ended_at": null,
  "updated_at": "2024-10-01T12:30:00.000Z",
  "host_ids": ["987654321"],
  "speaker_ids": ["111222333", "444555666"],
  "participant_count": 523,
  "total_replay_watched": 0,
  "is_ticketed": false,
  "creator": {
    "id": "987654321",
    "username": "tech_host",
    "name": "Tech Host",
    "profile_image_url": "https://pbs.twimg.com/profile_images/...",
    "verified": true
  },
  "topics": [
    {
      "id": "848920371311001600",
      "name": "Technology",
      "description": "All things tech"
    }
  ]
}

Response Fields

FieldTypeDescription
idstringUnique Space ID
statestringCurrent state (scheduled, live, ended, cancelled)
titlestringSpace title
participant_countintegerCurrent number of participants
host_idsarrayUser IDs of hosts
speaker_idsarrayUser IDs of speakers
creatorobjectSpace creator information
topicsarrayAssociated topics/categories
is_ticketedbooleanWhether Space requires payment
started_atstring|nullWhen Space started (ISO 8601)
ended_atstring|nullWhen Space ended (ISO 8601)

Common Use Cases

  1. Space Details: Display Space information in your app
  2. Live Monitoring: Check if Space is currently live
  3. Participant Tracking: Monitor participant counts
  4. Content Discovery: Find Spaces by topic or host

Search Spaces

Searches for Spaces based on keywords, state, and other criteria. Useful for discovering relevant Spaces.

Endpoint: GET /spaces/search

Query Parameters

NameTypeRequiredDescription
qstringYesSearch term (searches title, description, host names)
statestringNoFilter by state: live, scheduled, ended (Default: live)
limitintegerNoNumber of results (Default: 20, Max: 100)

Request Examples

# Search for live Spaces
curl --request GET \
  --url 'https://<direct.gateway>/spaces/search?q=technology&state=live&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Search for scheduled Spaces
curl --request GET \
  --url 'https://<direct.gateway>/spaces/search?q=AI&state=scheduled' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Search live Spaces
const liveSpaces = await fetch(
  'https://<direct.gateway>/spaces/search?q=technology&state=live',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
 
// Search scheduled Spaces
const scheduledSpaces = await fetch(
  'https://<direct.gateway>/spaces/search?q=AI&state=scheduled',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);

Response Example

{
  "data": [
    {
      "id": "1abcdefghijklmno",
      "state": "live",
      "title": "Tech Talk: The Future of AI",
      "participant_count": 523,
      "creator": {
        "username": "tech_host",
        "name": "Tech Host",
        "verified": true
      },
      "started_at": "2024-10-01T12:05:00.000Z"
    }
  ],
  "meta": {
    "result_count": 15
  }
}

Search Tips

  • Use specific keywords: More specific terms yield better results
  • Filter by state: Use state parameter to find live vs scheduled Spaces
  • Combine with topics: Search for Spaces in specific categories

Get Space Participants

Retrieves the complete list of participants in a Space, including hosts, speakers, and listeners with their roles.

Endpoint: GET /space/{space_id}/participants

Path Parameters

NameTypeRequiredDescription
space_idstringYesThe Space ID

Query Parameters

NameTypeRequiredDescription
limitintegerNoNumber of results (Default: 100, Max: 1000)
rolestringNoFilter by role: host, speaker, listener

Request Examples

# All participants
curl --request GET \
  --url 'https://<direct.gateway>/space/1abcdefghijklmno/participants?limit=100' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Only hosts
curl --request GET \
  --url 'https://<direct.gateway>/space/1abcdefghijklmno/participants?role=host' \
  --header 'X-API-KEY: YOUR_API_KEY'

JavaScript:

// Get all participants
const participants = await fetch(
  'https://<direct.gateway>/space/1abcdefghijklmno/participants',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
 
// Get only speakers
const speakers = await fetch(
  'https://<direct.gateway>/space/1abcdefghijklmno/participants?role=speaker',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);

Response Example

{
  "hosts": [
    {
      "id": "987654321",
      "username": "tech_host",
      "name": "Tech Host",
      "profile_image_url": "https://pbs.twimg.com/profile_images/...",
      "verified": true
    }
  ],
  "speakers": [
    {
      "id": "111222333",
      "username": "guest_speaker",
      "name": "Guest Speaker",
      "invited_at": "2024-10-01T12:00:00.000Z"
    }
  ],
  "listeners": [
    {
      "id": "444555666",
      "username": "listener_1",
      "joined_at": "2024-10-01T12:10:00.000Z"
    }
  ],
  "meta": {
    "total_participants": 523,
    "host_count": 1,
    "speaker_count": 3,
    "listener_count": 519
  }
}

Participant Roles

  • Hosts: Space creators and co-hosts, can manage the Space
  • Speakers: Users who can speak in the Space
  • Listeners: Users who are listening but not speaking

Get User Spaces

Retrieves all Spaces for a specific user, including Spaces they hosted, spoke in, or participated in.

Endpoint: GET /user/{user_id}/spaces

Path Parameters

NameTypeRequiredDescription
user_idstringYesThe user ID

Query Parameters

NameTypeRequiredDescription
statestringNoFilter by state: live, scheduled, ended
rolestringNoFilter by role: host, speaker, participant
limitintegerNoNumber of results (Default: 20, Max: 100)

Request Examples

# All Spaces for user
curl --request GET \
  --url 'https://<direct.gateway>/user/987654321/spaces?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Only live Spaces where user is host
curl --request GET \
  --url 'https://<direct.gateway>/user/987654321/spaces?state=live&role=host' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "data": [
    {
      "id": "1abcdefghijklmno",
      "state": "live",
      "title": "My Space",
      "participant_count": 523,
      "user_role": "host",
      "started_at": "2024-10-01T12:05:00.000Z"
    }
  ],
  "meta": {
    "result_count": 5
  }
}

Get Space Tweets

Retrieves tweets that mention or share a specific Space. Useful for finding discussions about a Space.

Endpoint: GET /space/{space_id}/tweets

Path Parameters

NameTypeRequiredDescription
space_idstringYesThe Space ID

Query Parameters

NameTypeRequiredDescription
limitintegerNoNumber of results (Default: 20, Max: 100)

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/space/1abcdefghijklmno/tweets?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Join me in this amazing space! 🎙️",
      "author": {
        "username": "space_promoter",
        "verified": false
      },
      "created_at": "2024-10-01T12:00:00.000Z",
      "space_share": {
        "space_id": "1abcdefghijklmno",
        "title": "Tech Talk: The Future of AI"
      }
    }
  ]
}

Get Scheduled Spaces

Retrieves all scheduled (upcoming) Spaces, optionally filtered by date range and topic.

Endpoint: GET /spaces/scheduled

Query Parameters

NameTypeRequiredDescription
fromstringNoStart date (ISO 8601)
tostringNoEnd date (ISO 8601)
topicstringNoTopic/Category filter
limitintegerNoNumber of results (Default: 20, Max: 100)

Request Examples

# All scheduled Spaces
curl --request GET \
  --url 'https://<direct.gateway>/spaces/scheduled?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Scheduled Spaces in date range
curl --request GET \
  --url 'https://<direct.gateway>/spaces/scheduled?from=2024-10-01&to=2024-10-07' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "data": [
    {
      "id": "1abcdefghijklmno",
      "state": "scheduled",
      "title": "Weekly Tech Roundup",
      "scheduled_start": "2024-10-02T15:00:00.000Z",
      "creator": {
        "username": "tech_host",
        "name": "Tech Host",
        "verified": true
      },
      "topics": ["Technology"],
      "is_ticketed": false,
      "reminder_count": 156
    }
  ],
  "meta": {
    "result_count": 12
  }
}

Get Live Spaces

Retrieves all currently live Spaces, with optional filters for topic and participant count.

Endpoint: GET /spaces/live

Query Parameters

NameTypeRequiredDescription
topicstringNoFilter by topic
min_participantsintegerNoMinimum participant count
verified_hosts_onlybooleanNoOnly Spaces with verified hosts
limitintegerNoNumber of results (Default: 20, Max: 100)

Request Examples

# All live Spaces
curl --request GET \
  --url 'https://<direct.gateway>/spaces/live?limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'
 
# Popular live Spaces (100+ participants)
curl --request GET \
  --url 'https://<direct.gateway>/spaces/live?min_participants=100' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "data": [
    {
      "id": "1abcdefghijklmno",
      "state": "live",
      "title": "Breaking News Discussion",
      "participant_count": 1523,
      "creator": {
        "username": "news_host",
        "verified": true
      },
      "started_at": "2024-10-01T11:00:00.000Z",
      "duration_minutes": 95
    }
  ],
  "meta": {
    "result_count": 45,
    "total_live_spaces": 523
  }
}

Get Space Recording

Retrieves recording information for an ended Space, including playback URLs and download links.

Endpoint: GET /space/{space_id}/recording

Path Parameters

NameTypeRequiredDescription
space_idstringYesThe Space ID

Request Example

curl --request GET \
  --url 'https://<direct.gateway>/space/1abcdefghijklmno/recording' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response Example

{
  "space_id": "1abcdefghijklmno",
  "state": "ended",
  "recording_available": true,
  "recording": {
    "media_key": "13_1234567890123456789",
    "duration_ms": 5400000,
    "playback_url": "https://...",
    "download_url": "https://...",
    "file_size_mb": 125.4
  },
  "total_replay_watched": 2340,
  "ended_at": "2024-10-01T13:30:00.000Z"
}

Notes

  • Not all Spaces have recordings (host must enable recording)
  • Recordings may take time to process after Space ends
  • recording_available indicates if recording exists

Space Topics/Categories

Spaces can be categorized by topics. Common topic IDs:

TopicID
Technology848920371311001600
Gaming849075377108226048
Music849075383444766721
Sports849075379953328129
News849075415688937472
Business849075381344018432
Entertainment849075385153028096

Using Topics

// Search Spaces by topic
const techSpaces = await fetch(
  '/spaces/search?q=technology&topic=848920371311001600',
  { headers: { 'X-API-KEY': API_KEY } }
);

Best Practices

Spaces-Specific Tips

  • Monitor live Spaces: Poll live Spaces every 30 seconds to track participant counts
  • Cache Space data: Spaces don't change frequently, cache for 2-5 minutes
  • Handle state changes: Space states update in near real-time (5-30 second delays are normal)
  • Check recording availability: Always check recording_available before requesting recordings

For general API best practices including error handling, rate limits, and performance optimization, see our Best Practices Guide.

3. Handle State Changes

Monitor state transitions for Spaces:

let previousState = null;
 
async function checkSpaceState(spaceId) {
  const space = await getCachedSpace(spaceId);
  
  if (previousState && previousState !== space.state) {
    console.log(`Space state changed: ${previousState} → ${space.state}`);
    
    if (space.state === 'live' && previousState === 'scheduled') {
      notifySpaceStarted(space);
    } else if (space.state === 'ended' && previousState === 'live') {
      notifySpaceEnded(space);
    }
  }
  
  previousState = space.state;
}

4. Filter by Relevance

Use search filters to find relevant Spaces:

async function findRelevantSpaces(keywords, minParticipants = 10) {
  const response = await fetch(
    `/spaces/live?min_participants=${minParticipants}`,
    { headers: { 'X-API-KEY': API_KEY } }
  );
  const data = await response.json();
  
  // Filter by keywords
  return data.data.filter(space => 
    keywords.some(keyword => 
      space.title.toLowerCase().includes(keyword.toLowerCase())
    )
  );
}

For comprehensive error handling and rate limits information, see our guides:

Troubleshooting

IssueSymptomsPossible CausesSolutions
Space state not updatingSpace state remains the same despite actual changesCaching too aggressively, not polling frequently enough, API delay in state updatesReduce cache TTL for live Spaces, poll more frequently for live Spaces, allow for slight delays (5-30 seconds) in state updates
Participant count inaccurateParticipant count doesn't match actual countReal-time updates have delays, participants joining/leaving rapidlyThis is normal - counts update in near real-time (every 10-30 seconds). Poll more frequently for accurate counts, use counts as approximate values

FAQ

How often do Space states update?

Space states update in near real-time, but there may be slight delays (5-30 seconds) for state changes.

Can I get real-time participant counts?

Yes, but counts update every 10-30 seconds. For real-time accuracy, poll frequently.

Are all Spaces recorded?

No, only Spaces where the host enabled recording. Check recording_available field.

How long are recordings available?

Recordings are typically available for 30 days after the Space ends, but this may vary.

Can I search for Spaces by host?

Yes, use the search endpoint with the host's username or search their Spaces via /user/{user_id}/spaces.

What's the difference between scheduled and live Spaces?

  • Scheduled: Has a future start time, not yet active
  • Live: Currently running, has active participants

Related Documentation

TrendsLists & Communities