GET /2/spaces/by/creator_ids

Returns live or scheduled Spaces created by the specified user IDs. Up to 100 comma-separated IDs can be looked up using this endpoint.



Endpoint URL

https://api.twitter.com/2/spaces/by/creator_ids

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

Rate limit

App rate limit: 300 requests per 15-minute window

Query parameters

NameTypeDescription
user_ids
 Required 
stringA comma separated list of user IDs (up to 100).
expansions
 Optional 
enum (invited_user_ids, speaker_ids, creator_id, host_ids)Expansions enable you to request additional data objects that relate to the originally returned Space. Submit a list of desired expansions in a comma-separated list. The ID that represents the expanded data object will be included directly in the Space data object, but the expanded object metadata will be returned within the includes response object, and will also include the ID so that you can match this data object to the original Space object.

The following data objects can be expanded using this parameter:
  • The Spaces creator's user object
  • The user objects of any Space co-host
  • Any mentioned users’ object
  • Any speaker's user object
space.fields
 Optional 
enum (host_ids, created_at, creator_id, id, lang, invited_user_ids, participant_count, speaker_ids, started_at, state, title, updated_at, scheduled_start, is_ticketed)This fields parameter enables you to select which specific Space fields will deliver in each returned Space. Specify the desired fields in a comma-separated list.
user.fields
 Optional 
enum (created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld)This fields parameter enables you to select which specific user fields will deliver in each returned Tweet. Specify the desired fields in a comma-separated list without spaces between commas and fields. While the user ID will be located in the original Space object, you will find this ID and all additional user fields in the includes data object.


Example requests

      curl "https://api.twitter.com/2/spaces/by/creator_ids?user_ids=2244994945,6253282" -H "Authorization: Bearer $BEARER_TOKEN"
    
      curl "https://api.twitter.com/2/spaces/by/creator_ids?user_ids=2244994945,6253282?space.fields=host_ids" -H "Authorization: Bearer $BEARER_TOKEN"
    

Example responses

      {
  "data": [
    {
      "id": "1DXxyRYNejbKM",
      "state": "live"
    }
  ],
  "meta": {
    "result_count": 2
  }
}
    
      {
  "data": [
    {
      "host_ids": [
        "2244994945"
      ],
      "id": "1DXxyRYNejbKM",
      "state": "live"
    },
    {
      "host_ids": [
        "6253282"
      ],
      "id": "1nAJELYEEPvGL",
      "state": "scheduled"
    }
  ],
  "meta": {
    "result_count": 2
  }
}
    

Response fields

NameTypeDescription
id
 Default 
stringUnique identifier of this Space.
host_idsarrayAn array containing the user ID of each Space co-host. These IDs are returned as strings in order to avoid complications with languages and tools that cannot handle large integers.

To return this field, add space.fields=host_ids in the request's query parameter.

You can obtain the expanded object in includes.users by adding expansions=host_ids in the request's query parameter.
created_atdate (ISO 8601)Creation date and time of this Space. For scheduled Spaces, this indicates the time the Space was created, not the time when the Space will start.

To return this field, add space.fields=created_at in the request's query parameter.
creator_idstringThe user ID of the account that created this Space. This ID is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

To return this field, add space.fields=creator_id in the request's query parameter.

You can obtain the expanded object in includes.users by adding expansions=creator_id in the request's query parameter.
langstringMain language of the Space’s creator, as inferred by Twitter (this may differ from the language spoken in the Space). Returned as a BCP 47 language tag.

Supported values:
  • Arabic (ar)
  • Armenian (hy)
  • Chinese (zh)
  • Danish (da)
  • English (en)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Hindi (hi)
  • Hebrew (iw)
  • Indonesian (in)
  • Italian (it)
  • Japanese (ja)
  • Kazakh (kk)
  • Korean (ko)
  • Norwegian (no)
  • Polish (pl)
  • Portuguese (pt)
  • Romanian (ro)
  • Russian (ru)
  • Spanish (es)
  • Swedish (sv)
  • Turkish (tr)
  • Ukranian (uk)


To return this field, add space.fields=lang in the request's query parameter.
is_ticketedbooleanIndicates if this is a ticketed Space.

To return this field, add space.fields=is_ticketed in the request's query parameter.
invited_user_idsarrayThe list of user IDs that can automatically join as Speakers. Usually, users in this list are invited to speak via the Invite user option and have a Speaker role when the Space starts.

These IDs are returned as strings in order to avoid complications with languages and tools that cannot handle large integers.

To return this field, add space.fields=invited_user_ids in the request's query parameter.

You can obtain the expanded object in includes.users by adding expansions=invited_user_ids in the request's query parameter.
participant_countintegerThe current number of users in the Space, including Hosts and Speakers.

To return this field, add space.fields=participant_count in the request's query parameter.
scheduled_startdate (ISO 8601)Indicates the scheduled start time of a 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.

To return this field, add space.fields=scheduled_start in the request's query parameter.
speaker_idsarrayThe 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.

These IDs are returned as strings in order to avoid complications with languages and tools that cannot handle large integers.These IDs are returned as strings in order to avoid complications with languages and tools that cannot handle large integers.

To return this field, add space.fields=speaker_ids in the request's query parameter.

You can obtain the expanded object in includes.users by adding expansions=speaker_ids in the request's query parameter.
started_atdate (ISO 8601)The start date and time of the Space. Only available if the space has started.

To return this field, add space.fields=started_at in the request's query parameter.
state
 Default 
enum (live, scheduled)Indicates whether the Space is scheduled and hasn’t started yet (scheduled) or if it’s in progress (live).

To return this field, add space.fields=state in the request's query parameter.
titlestringThe title of this Space as specified by the creator.

To return this field, add space.fields=title in the request's query parameter.
updated_atdate (ISO 8601)The timestamp of the last update to any of this Space's metadata, such as the title or scheduled time.

To return this field, add space.fields=updated_at in the request's query parameter.
includesobjectIf you include an expansion parameter, the referenced objects will be returned if available.
includes.usersarrayWhen including the expansions=author_id parameter, this includes a list of referenced Tweet authors in the form of user objects with their default fields and any additional fields requested using the user.fields parameter.
errorsobjectContains details about errors that affected any of the requested Tweets. See Status codes and error messages for more details.
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.