Spaces & Audio – Twitter API

Docs

Spaces & Audio

Access Twitter Spaces data including live and recorded audio rooms.

Overview

The Spaces endpoints provide access to Twitter Spaces, including live rooms, recordings, participant lists, and host information.

Endpoints

Get Space by ID

Retrieves details about a Twitter Space.

GET /space/{space_id}

Parameters

Name	Type	Required	Description
`space_id`	string	Yes	The unique Space ID

Headers

X-API-KEY: <YOUR_API_KEY>

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://..."
  },
  "topics": [
    {
      "id": "848920371311001600",
      "name": "Technology",
      "description": "All things tech"
    }
  ]
}

Search Spaces

Searches for live or scheduled Spaces.

GET /spaces/search

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search term
`state`	string	No	`live`, `scheduled`, `ended` (Default: live)
`limit`	integer	No	Number of results (Default: 20, Max: 100)

Response Example

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

Get Space Participants

Retrieves the participant list of a Space.

GET /space/{space_id}/participants

Parameters

Name	Type	Required	Description
`space_id`	string	Yes	The Space ID
`limit`	integer	No	Number of results (Default: 100, Max: 1000)
`role`	string	No	Filter: `host`, `speaker`, `listener`

Response Example

{
  "hosts": [
    {
      "id": "987654321",
      "username": "tech_host",
      "name": "Tech Host",
      "profile_image_url": "https://...",
      "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
  }
}

Get User Spaces

Retrieves all Spaces for a user (hosted or participated in).

GET /user/{user_id}/spaces

Parameters

Name	Type	Required	Description
`user_id`	string	Yes	The user ID
`state`	string	No	`live`, `scheduled`, `ended`
`role`	string	No	`host`, `speaker`, `participant`
`limit`	integer	No	Number of results (Default: 20, Max: 100)

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 Space.

GET /space/{space_id}/tweets

Parameters

Name	Type	Required	Description
`space_id`	string	Yes	The Space ID
`limit`	integer	No	Number of results (Default: 20, Max: 100)

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Join me in this amazing space! 🎙️",
      "author": {...},
      "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 Spaces.

GET /spaces/scheduled

Parameters

Name	Type	Required	Description
`from`	string	No	Start date (ISO 8601)
`to`	string	No	End date (ISO 8601)
`topic`	string	No	Topic/Category
`limit`	integer	No	Number of results (Default: 20, Max: 100)

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"
      },
      "topics": ["Technology"],
      "is_ticketed": false,
      "reminder_count": 156
    }
  ],
  "meta": {
    "result_count": 12
  }
}

Get Live Spaces

Retrieves all currently live Spaces.

GET /spaces/live

Parameters

Name	Type	Required	Description
`topic`	string	No	Filter by topic
`min_participants`	integer	No	Minimum participant count
`verified_hosts_only`	boolean	No	Only verified hosts
`limit`	integer	No	Number of results (Default: 20, Max: 100)

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.

GET /space/{space_id}/recording

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"
}

Space States

State	Description
`scheduled`	Space is scheduled but not yet started
`live`	Space is currently running
`ended`	Space has ended
`cancelled`	Space was cancelled

Space Topics/Categories

Common topic IDs:

Topic	ID
Technology	848920371311001600
Gaming	849075377108226048
Music	849075383444766721
Sports	849075379953328129
News	849075415688937472

Rate Limits

Basic Plan: 50 Requests/hour
Pro Plan: 500 Requests/hour
Enterprise Plan: 5,000 Requests/hour

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API Key
404	Not Found - Space does not exist
403	Forbidden - Access to private Space denied
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error