GET /2/spaces/search

GET /2/spaces/search

Return live or scheduled Spaces matching your specified search terms. This endpoint performs a keyword search, meaning that it will return Spaces that are an exact case-insensitive match of the specified search term. The search term will match the original title of the Space.

Endpoint URL

https://api.twitter.com/2/spaces/search

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 App-only

OAuth 2.0 Authorization Code with PKCE

Rate limit

User rate limit (User context): 300 requests per 15-minute window per each authenticated user

App rate limit (Application-only): 300 requests per 15-minute window shared among all users of your app

OAuth 2.0 scopes required by this endpoint

tweet.read

users.read

space.read

Learn more about OAuth 2.0 Authorization Code with PKCE

Query parameters

NameTypeDescription
query
 Required 
stringYour search term. This can be any text (including mentions and Hashtags) present in the title of the Space.
expansions
 Optional 
enum (invited_user_ids, speaker_ids, creator_id, host_ids, topics_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, ended_at, subscriber_count, topic_ids, 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.
state
 Optional 
enum (all, live, scheduled)Determines the type of results to return. This endpoint returns all Spaces by default. Use live to only return live Spaces or scheduled to only return upcoming Spaces.
topic.fields
 Optional 
enum (id, name, description)This fields parameter enables you to select which specific topic metadata in each returned Space topic object, if the creator of the Space set one or more topics. 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 Space. 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 code with offical SDKs

TypeScript
Java
      (async () => {
  try {
    const spacesSearch = await twitterClient.spaces.searchSpaces({
      //The search query
      query: "hello",

      // A comma separated list of Space fields to display.
      "space.fields": ["title", "host_ids"],
    });
    console.dir(spacesSearch, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

    
      // Set the params values
// For full list of params visit - https://github.com/twitterdev/twitter-api-java-sdk/blob/main/docs/SpacesApi.md#searchSpaces

// String | The search query
String query = "hello";

// Set<String> | A comma separated list of Space fields to display.
Set<String> spaceFields = new HashSet<>(Arrays.asList("title", "host_ids"));

try {
    MultiSpaceLookupResponse result = apiInstance.spaces().searchSpaces(query, null, null, spaceFields, null, null, null);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling SpacesApi#searchSpaces");
    System.err.println("Status code: " + e.getCode());
    System.err.println("Reason: " + e.getResponseBody());
    System.err.println("Response headers: " + e.getResponseHeaders());
    e.printStackTrace();
}

    

Example responses

Response
      {
  "data": [
    {
      "host_ids": [
        "2244994945"
      ],
      "id": "1DXxyRYNejbKM",
      "state": "live",
      "title": "hello world 👋"
    },
    {
      "host_ids": [
        "6253282"
      ],
      "id": "1nAJELYEEPvGL",
      "state": "scheduled",
      "title": "Say hello to the Spaces endpoints"
    }
  ],
  "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.
ended_atdate (ISO 8601)End date and time of this Space. This field will be only present for Spaces in the ended state.

To return this field, add space.fields=ended_at 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.
subscriber_countintegerIndicates the number of people who set a remainder to this Space. This field can only be requested if your app is authentic the request using the Access Token of the creator of the Space.

To return this field, add space.fields=subscriber_count in the request's query parameter.
topic_idsstringA list of the Space topic IDs, if set by the creator of the Space.

To return this field, add space.fields=topic_ids in the request's query parameter.
topics.idstringThe ID of the Space topic.

To return this field, add topic.fields=topics.id in the request's query parameter.

You can obtain the expanded object in includes.topics by adding expansions=topics in the request's query parameter.
topics.idstringThe ID of the Space topic.

To return this field, add topic.fields=topics.id in the request's query parameter.

You can obtain the expanded object in includes.topics by adding expansions=topics in the request's query parameter.
topics.namestringThe name of the Space topic.

To return this field, add topic.fields=topics.name in the request's query parameter.

You can obtain the expanded object in includes.topics by adding expansions=topics in the request's query parameter.
topics.namestringA full text description of the Space topic.

To return this field, add topic.fields=topics.name in the request's query parameter.

You can obtain the expanded object in includes.topics by adding expansions=topics 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.