X Spaces API

openapi: 3.2.0
info:
  description: X API v2 core endpoints
  version: '2.168'
  title: X API v2 Spaces API
  termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
  contact:
    name: X Developers
    url: https://developer.x.com/
  license:
    name: X Developer Agreement and Policy
    url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
  url: https://api.x.com
tags:
- name: Spaces
  description: Endpoints related to retrieving, managing Spaces
  externalDocs:
    description: Find out more
    url: https://docs.x.com/x-api/spaces/introduction
paths:
  /2/spaces:
    get:
      security:
      - OAuth2UserToken:
        - space.read
        - users.read
        - tweet.read
      - BearerToken: []
      tags:
      - Spaces
      summary: Get Spaces by IDs
      operationId: getSpacesByIds
      parameters:
      - name: ids
        in: query
        required: true
        schema:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            pattern: ^[a-zA-Z0-9]{1,13}$
        explode: false
        style: form
      - $ref: '#/components/parameters/SpaceFieldsParameter'
      - $ref: '#/components/parameters/SpaceExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/TopicFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpacesByIdsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/spaces/by/creator_ids:
    get:
      security:
      - OAuth2UserToken:
        - users.read
        - space.read
        - tweet.read
      - BearerToken: []
      tags:
      - Spaces
      summary: Get Spaces by Creator IDs
      operationId: getSpacesByCreatorIds
      parameters:
      - name: user_ids
        in: query
        required: true
        schema:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            pattern: ^[0-9]{1,19}$
        explode: false
        style: form
      - $ref: '#/components/parameters/SpaceFieldsParameter'
      - $ref: '#/components/parameters/SpaceExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/TopicFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpacesByCreatorIdsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/spaces/search:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - users.read
        - space.read
      - BearerToken: []
      tags:
      - Spaces
      summary: Search Spaces
      description: Retrieves a list of Spaces matching the specified search query.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/spaces/search/api-reference/get-spaces-search
      operationId: searchSpaces
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 2048
        style: form
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum:
          - live
          - scheduled
          - all
          default: all
        style: form
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - $ref: '#/components/parameters/SpaceFieldsParameter'
      - $ref: '#/components/parameters/SpaceExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/TopicFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSpacesResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/spaces/{id}:
    get:
      security:
      - OAuth2UserToken:
        - users.read
        - space.read
        - tweet.read
      - BearerToken: []
      tags:
      - Spaces
      summary: Get Spaces by ID
      operationId: getSpacesById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - $ref: '#/components/parameters/SpaceFieldsParameter'
      - $ref: '#/components/parameters/SpaceExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/TopicFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpacesByIdResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/spaces/{id}/buyers:
    get:
      security:
      - OAuth2UserToken:
        - users.read
        - space.read
        - tweet.read
      tags:
      - Spaces
      summary: Get Space ticket buyers
      description: Retrieves a list of Users who purchased tickets to a specific Space by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-buyers
      operationId: getSpacesBuyers
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A base32hex-encoded pagination token.
        required: false
        schema:
          type: string
          minLength: 16
        style: form
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/UserExpansionsParameter'
      - $ref: '#/components/parameters/PostFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpacesBuyersResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /2/spaces/{id}/tweets:
    get:
      security:
      - OAuth2UserToken:
        - tweet.read
        - space.read
        - users.read
      - BearerToken: []
      tags:
      - Spaces
      summary: Get Space Posts
      description: Retrieves a list of Posts shared in a specific Space by its ID.
      externalDocs:
        url: https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id-tweets
      operationId: getSpacesPosts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9]{1,13}$
        style: simple
      - name: max_results
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          format: int32
          default: 100
        style: form
      - name: pagination_token
        in: query
        description: A base32hex-encoded pagination token.
        required: false
        schema:
          type: string
        style: form
      - $ref: '#/components/parameters/PostFieldsParameter'
      - $ref: '#/components/parameters/PostExpansionsParameter'
      - $ref: '#/components/parameters/UserFieldsParameter'
      - $ref: '#/components/parameters/MediaFieldsParameter'
      - $ref: '#/components/parameters/PollFieldsParameter'
      - $ref: '#/components/parameters/PlaceFieldsParameter'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSpacesPostsResponse'
        default:
          description: The request has failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    GetSpacesBuyersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
        meta:
          type: object
          properties:
            next_token:
              type: string
              description: Pagination token for the next page of results.
            previous_token:
              type: string
              description: Pagination token for the previous page of results.
            result_count:
              type: integer
              description: Number of items in the data array.
              format: int32
    PostPublicMetrics:
      type: object
      description: Engagement metrics for the Post at the time of the request.
      required:
      - repost_count
      - reply_count
      - like_count
      - quote_count
      - bookmark_count
      - impression_count
      properties:
        bookmark_count:
          type: integer
          description: Number of times this Post has been bookmarked.
          format: int64
        impression_count:
          type: integer
          description: Number of times this Post has been viewed.
          format: int64
        like_count:
          type: integer
          description: Number of likes on this Post.
          format: int64
        quote_count:
          type: integer
          description: Number of quote Posts of this Post.
          format: int64
        reply_count:
          type: integer
          description: Number of replies to this Post.
          format: int64
        repost_count:
          type: integer
          description: Number of times this Post has been reposted.
          format: int64
    PostDisplayTextRange:
      type: array
      description: The inclusive start and exclusive end indices of the displayable content of the Post.
      minItems: 2
      maxItems: 2
      items:
        type: integer
        format: int64
    Expansions:
      type: object
      properties:
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        places:
          type: array
          items:
            $ref: '#/components/schemas/Place'
        polls:
          type: array
          items:
            $ref: '#/components/schemas/Poll'
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        topics:
          type: array
          items:
            $ref: '#/components/schemas/Topic'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Media:
      type: object
      properties:
        alt_text:
          type: string
        duration_ms:
          type: integer
        height:
          type: integer
        media_key:
          type: string
        non_public_metrics:
          $ref: '#/components/schemas/MediaNonPublicMetrics'
        organic_metrics:
          $ref: '#/components/schemas/MediaOrganicMetrics'
        preview_image_url:
          type: string
        promoted_metrics:
          $ref: '#/components/schemas/MediaPromotedMetrics'
        public_metrics:
          $ref: '#/components/schemas/MediaPublicMetrics'
        type:
          type: string
        url:
          type: string
        variants:
          $ref: '#/components/schemas/MediaVariants'
        width:
          type: integer
    SpaceHostIds:
      type: array
      description: A list of unique identifiers of the Users who host this Space.
      items:
        type: string
    PostGeo:
      type: object
      description: The location tagged on the Post, if the user provided one.
      properties:
        coordinates:
          type:
          - object
          - 'null'
          description: A GeoJSON Point geometry.
          required:
          - type
          - coordinates
          properties:
            coordinates:
              type: array
              description: '[longitude, latitude].'
              minItems: 2
              maxItems: 2
              items:
                type: number
                format: double
            type:
              type: string
              description: The GeoJSON geometry type.
              enum:
              - Point
        place_id:
          type:
          - string
          - 'null'
          description: The unique identifier of the tagged place.
    FieldHydrationFailureProblem:
      type: object
      required:
      - type
      - title
      - detail
      - field
      properties:
        detail:
          type: string
        field:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/field-hydration-failure
    PostSuggestedSourceLinks:
      type: array
      description: URLs suggested as sources for this Post.
      items:
        type: string
    NotAuthorizedForResourceProblem:
      type: object
      required:
      - type
      - title
      - detail
      - resource_type
      properties:
        detail:
          type: string
        parameter:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/not-authorized-for-resource
        value:
          type: string
    PostEntities:
      type: object
      description: A list of metadata entities (hashtags, mentions, URLs) found in the Post text.
      properties:
        cashtags:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A hashtag or cashtag entity.
            required:
            - start
            - end
            - tag
            properties:
              end:
                type: integer
                description: End index in the text (exclusive).
                format: int64
              start:
                type: integer
                description: Start index in the text (inclusive).
                format: int64
              tag:
                type: string
        hashtags:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A hashtag or cashtag entity.
            required:
            - start
            - end
            - tag
            properties:
              end:
                type: integer
                description: End index in the text (exclusive).
                format: int64
              start:
                type: integer
                description: Start index in the text (inclusive).
                format: int64
              tag:
                type: string
        mentions:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A user mention entity.
            required:
            - start
            - end
            properties:
              end:
                type: integer
                format: int64
              id:
                type:
                - string
                - 'null'
              start:
                type: integer
                format: int64
              username:
                type:
                - string
                - 'null'
        urls:
          type:
          - array
          - 'null'
          items:
            type: object
            description: A URL entity found in the Post text, enriched with link metadata.
            required:
            - start
            - end
            properties:
              description:
                type:
                - string
                - 'null'
                description: Description of the linked page, when available.
              display_url:
                type:
                - string
                - 'null'
                description: The URL as displayed in the Post text.
              end:
                type: integer
                format: int64
              expanded_url:
                type:
                - string
                - 'null'
                description: The fully resolved URL.
              images:
                type:
                - array
                - 'null'
                items:
                  type: object
                  description: A preview image for a linked page.
                  properties:
                    height:
                      type:
                      - integer
                      - 'null'
                      format: int64
                    url:
                      type:
                      - string
                      - 'null'
                    width:
                      type:
                      - integer
                      - 'null'
                      format: int64
              media_key:
                type:
                - string
                - 'null'
              start:
                type: integer
                format: int64
              status:
                type:
                - integer
                - 'null'
                description: HTTP status from resolving the URL.
                format: int64
              title:
                type:
                - string
                - 'null'
                description: Title of the linked page, when available.
              unwound_url:
                type:
                - string
                - 'null'
                description: The final destination after following redirects.
              url:
                type:
                - string
                - 'null'
                description: The t.co shortened URL.
    MediaVariants:
      type: array
      description: Each media object may have multiple display or playback variants, with different resolutions or formats.
      items:
        type: object
        description: A single playback or display variant of a media object.
        properties:
          bit_rate:
            type:
            - integer
            - 'null'
            description: The bit rate of this variant, in bits per second. Absent for playlist variants.
            format: int64
          content_type:
            type:
            - string
            - 'null'
            description: The MIME type of this variant, for example "video/mp4" or "application/x-mpegURL".
          url:
            type:
            - string
            - 'null'
            description: The URL to this media variant.
    PostReferencedPosts:
      type: array
      description: A list of Posts this Post refers to. If the Post is a Retweet, Quote or Reply, it includes the referenced Post's type and ID.
      items:
        type: object
        description: A reference from this Post to another Post (repost, quote, or reply).
        required:
        - type
        - id
        properties:
          id:
            type: string
            description: Unique identifier of the referenced Post.
          type:
            description: How this Post references the other Post.
            oneOf:
            - type: string
              description: The kind of Post-to-Post reference.
              enum:
              - retweeted
              - quoted
              - replied_to
    GetSpacesByIdResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Space'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
    GetSpacesPostsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
        meta:
          type: object
          properties:
            next_token:
              type: string
              description: Pagination token for the next page of results.
            previous_token:
              type: string
              description: Pagination token for the previous page of results.
            result_count:
              type: integer
              description: Number of items in the data array.
              format: int32
    MediaNonPublicMetrics:
      type: object
      description: Nonpublic engagement metrics for the media at the time of the request.
      properties:
        playback_0_count:
          type:
          - integer
          - 'null'
          description: Number of users who started playback (0% quartile) of this video.
          format: int64
        playback_100_count:
          type:
          - integer
          - 'null'
          description: Number of users who completed playback (100% quartile) of this video.
          format: int64
        playback_25_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 25% of this video.
          format: int64
        playback_50_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 50% of this video.
          format: int64
        playback_75_count:
          type:
          - integer
          - 'null'
          description: Number of users who watched at least 75% of this video.
          format: int64
    UserConnectionStatus:
      type: array
      description: Returns detailed information about the relationship between two users.
      items:
        type: string
        description: A connection between the authenticated User and this User.
        enum:
        - blocking
        - follow_request_received
        - follow_request_sent
        - followed_by
        - following
        - muting
    GetSpacesByCreatorIdsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Space'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Problem'
        includes:
          $ref: '#/components/schemas/Expansions'
        meta:
          type: object
          properties:
            result_count:
              type: integer
              description: Number of items in the data array.
              format: int32
    Space:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        creator_id:
          type: string
        ended_at:
          type: string
          format: date-time
        host_ids:
          $ref: '#/components/schemas/SpaceHostIds'
        id:
          type: string
        invited_user_ids:
          $ref: '#/components/schemas/SpaceInvitedUserIds'
        is_ticketed:
          type: boolean
        lang:
          type: string
        participant_count:
          type: integer
        scheduled_start:
          type: string
          format: date-time
        speaker_ids:
          $ref: '#/components/schemas/SpaceSpeakerIds'
        started_at:
          type: string
          format: date-time
        state:
          type: string
        subscriber_count:
          type: integer
        title:
          type: string
        topic_ids:
          $ref: '#/components/schemas/SpaceTopicIds'
        updated_at:
          type: string
          format: date-time
    NotAuthorizedForFieldProblem:
      type: object
      required:
      - type
      - title
      - detail
      - field
      properties:
        detail:
          type: string
        field:
          type: string
        parameter:
          type: string
        resource_id:
          type: string
        resource_type:
          type: string
        section:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
          enum:
          - https://api.x.com/2/problems/not-authorized-for-field
        value:
          type: string
    PostNotePost:
      type: object
      description: The full content of the Post, including text beyond 280 characters.
      required:
      - text
      properties:
        entities:
          type:
          - object
          - 'null'
          description: Metadata entities (hashtags, cashtags, mentions, URLs) found in the note Post text.
          properties:
            cashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            hashtags:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A hashtag or cashtag entity.
                required:
                - start
                - end
                - tag
                properties:
                  end:
                    type: integer
                    description: End index in the text (exclusive).
                    format: int64
                  start:
                    type: integer
                    description: Start index in the text (inclusive).
                    format: int64
                  tag:
                    type: string
            mentions:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A user mention entity.
                required:
                - start
                - end
                properties:
                  end:
                    type: integer
                    format: int64
                  id:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  username:
                    type:
                    - string
                    - 'null'
            urls:
              type:
              - array
              - 'null'
              items:
                type: object
                description: A URL entity found in note Post text.
                required:
                - start
                - end
                properties:
                  display_url:
                    type:
                    - string
                    - 'null'
                  end:
                    type: integer
                    format: int64
                  expanded_url:
                    type:
                    - string
                    - 'null'
                  start:
                    type: integer
                    format: int64
                  url:
                    type:
                    - string
                    - 'null'
        text:
          type: string
          description: The full note text of the Post.
    Post:
      type: object
      properties:
        article:
          type: object
        article_title:
          type: object
          description: Metadata about the long-form Article attached to this Post, if any.
        attachments:
          $ref: '#/components/schemas/PostAttachments'
        author_id:
          type: string
          description: Unique identifier of the author of this Post.
        card_uri:
          type: string
        community_id:
          type: string
          description: The unique identifier of the Community this Post belongs to, if any.
        context_annotations:
          $ref: '#/components/schemas/PostContextAnnotations'
        conversation_id:
          type: string
          description: The ID of the conversation this Post belongs to (matches the root Post's ID).
        created_at:
          type: string
          description: Creation time of the Post.
          format: date-time
        display_text_range:
          $ref: '#/components/schemas/PostDisplayTextRange'
        edit_controls:
          $ref: '#/components/schemas/PostEditControls'
        edit_history_post_ids:
          type: array
          description: A list of Post IDs in this Post's edit history chain.
          items:
            type: string
        entities:
          $ref: '#/components/schemas/PostEntities'
        geo:
          $ref: '#/components/schemas/PostGeo'
        id:
          type: string
          description: Unique identifier of this Post.
        in_reply_to_user_id:
          type: string
          description: Unique identifier of the User this Post is replying to.
        lang:
          type: string
          description: Language of the Post, if detected by X. Returned as a BCP47 language tag.
        matched_media_notes:
          $ref: '#/components/schemas/PostMatchedMediaNotes'
        media_metadata:
          $ref: '#/components/schemas/PostMediaMetadata'
        non_public_metrics:
          type: object
          description: Nonpublic engagement metrics for the Post at the time of the request.
        note_post:
          $ref: '#/components/schemas/PostNotePost'
        note_request_suggestions:
          $ref: '#/components/schemas/PostNoteRequestSuggestions'
        organic_metrics:
          type: object
          description: Organic nonpublic engagement metrics for the Post at the time of the request.
        paid_partnership:
          type: boolean
          description: Indicates if this Post is a paid partnership, i.e. it has been disclosed by the author as containing paid promotion.
        possibly_sensitive:
          type: boolean
          description: Indicates if this Post contains URLs marked as sensitive, for example content suitable for mature audiences

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/x/refs/heads/main/openapi/x-spaces-api-openapi.yml