Space

Spaces allow expression and interaction via live audio conversations. The Space data dictionary contains relevant metadata about a Space; all the details are updated in real time.

User objects can found and expanded in the user resource. These objects are available for expansion by adding at least one of host_ids, creator_id, speaker_ids, mentioned_user_ids to the expansions query parameter.

Unlike Tweets, Spaces are ephemeral and become unavailable after they end or when they are canceled by their creator. When your app handles Spaces data, you are responsible for returning the most up-to-date information, and must remove data that is no longer available from the platform. The Spaces lookup endpoints can help you ensure you respect the users’ expectations and intent.

 

Field value Type Description How it can be used
id (default) string

The unique identifier of the requested Space.

"id": "1zqKVXPQhvZJB"

Uniquely identify a Space returned in the response.

state (default)

string

Indicates if the Space has started or will start in the future, or if it has ended.

"state": "live"


Filter live or scheduled Spaces.

created_at

date (ISO 8601)

Creation time of this Space.

"created_at": "2021-07-04T23:12:08.000Z"

Understand when a Space was first created and sort Spaces by creation time. 

host_ids

array

The unique identifier of the Users who are hosting this Space.

"host_ids": [
  "2244994945",
   "6253282"
]

Expand User objects, understand engagement.

lang

string

Language of the Space, if detected by Twitter. Returned as a BCP47 language tag.

"lang": "en"

Classify Spaces by inferred language.

is_ticketed

boolean

Indicates is this is a ticketed Space.

"is_ticketed": false


Create user experiences to highlight content of interest.

invited_user_ids

array

The list of user IDs that were invited to join as speakers. Usually, users in this list are invited to speak via the Invite user option.

"mentioned_user_ids": [
  "2244994945",
   "6253282"
]

Expand User objects, understand engagement.

participant_count

integer

The current number of users in the Space, including Hosts and Speakers.

"participant_count": 420

 

Understand engagement, and create reports and visualizations for creators.

scheduled_start

date (ISO 8601)

Indicates the start time of a scheduled Space, as set by the creator of the Space. This field is returned only if the Space has been scheduled; in other words, if the field is returned, it means the Space is a scheduled Space.

"scheduled_start": "2021-07-14T08:00:00.000Z"

Integrate with calendar notifications, filter and sort Spaces by time.

speaker_ids

array

The list of users who were speaking at any point during the Space. This list contains all the users in invited_user_ids in addition to any user who requested to speak and was allowed via the Add speaker option.

 

"speaker_ids": [
  "2244994945",
   "6253282"
]

Expand User objects, understand engagement.

started_at

date (ISO 8601)

Indicates the actual start time of a Space.

 

"started_at": "2021-07-14T08:00:12.000Z"

 

Determine start time of a Space.

title

string

The title of the Space as specified by the creator.

"title": "Say hello to the Space data object!"

Determine the title of a Space, understand referenced keywords, hashtags, and mentions.

updated_at date (ISO 8601) Specifies the date and time of the last update to any of the Space's metadata, such as its title or scheduled time.

"updated_at": "2021-07-11T14:44:44.000Z"
Keep information up to date.


Retrieving a Space object

Sample Request

In the following request, we are requesting fields for the Space on the Spaces lookup endpoint. Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.
 

      curl "https://api.twitter.com/2/spaces/1DXxyRYNejbKM?space.fields=created_at,creator_id,created_athost_ids,lang,is_ticketed,invited_user_ids,participant_count,scheduled_start,speaker_ids,started_at,state,title,updated_at&expansions=creator_id,host_ids,invited_user_ids,speaker_ids" --header "Authorization: Bearer $BEARER_TOKEN"
    


Sample Response
 

      {
    "data": {
        "id": "1zqKVXPQhvZJB",
        "state": "live",
        "created_at": "2021-07-04T23:12:08.000Z",
        "host_ids": [
          "2244994945",
          "6253282"
        ],
        "lang": "en",
        "is_ticketed": false,
        "invited_user_ids": [
          "2244994945",
          "6253282"
        ],
        "participant_count": 420,
        "scheduled_start": "2021-07-14T08:00:00.000Z",
        "speaker_ids": [
          "2244994945",
          "6253282"
        ],        
        "started_at": "2021-07-14T08:00:12.000Z",
        "title": "Say hello to the Space data object!",
        "updated_at": "2021-07-11T14:44:44.000Z"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "Twitter Dev",
                "username": "TwitterDev"
           },
           {
            "id": "6253282",
            "name": "Twitter API",
            "username": "TwitterAPI"
          }
    ]
    }
}
    
Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.