X API v2 — Tweets

naftiko: 1.0.0-alpha2
info:
  label: X API v2 — Tweets
  description: 'X API v2 — Tweets. 38 operations. Lead operation: X Get 28-hour Post Insights. Self-contained Naftiko capability
    covering one Twitter business surface.'
  tags:
  - Twitter
  - Tweets
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TWITTER_API_KEY: TWITTER_API_KEY
capability:
  consumes:
  - type: http
    namespace: x-tweets
    baseUri: https://api.x.com
    description: X API v2 — Tweets business capability. Self-contained, no shared references.
    resources:
    - name: 2-insights-28hr
      path: /2/insights/28hr
      operations:
      - name: getinsights28hr
        method: GET
        description: X Get 28-hour Post Insights
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: tweet_ids
          in: query
          type: array
          description: List of PostIds for 28hr metrics.
          required: true
        - name: granularity
          in: query
          type: string
          description: granularity of metrics response.
          required: true
        - name: requested_metrics
          in: query
          type: array
          description: request metrics for historical request.
          required: true
    - name: 2-insights-historical
      path: /2/insights/historical
      operations:
      - name: getinsightshistorical
        method: GET
        description: X Get Historical Post Insights
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: tweet_ids
          in: query
          type: array
          description: List of PostIds for historical metrics.
          required: true
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
          required: true
        - name: granularity
          in: query
          type: string
          description: granularity of metrics response.
          required: true
        - name: requested_metrics
          in: query
          type: array
          description: request metrics for historical request.
          required: true
    - name: 2-lists-id-tweets
      path: /2/lists/{id}/tweets
      operations:
      - name: getlistsposts
        method: GET
        description: X Get List Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the List.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
    - name: 2-spaces-id-buyers
      path: /2/spaces/{id}/buyers
      operations:
      - name: getspacesbuyers
        method: GET
        description: X Get Space Ticket Buyers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Space to be retrieved.
          required: true
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get a specified 'page' of results.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
    - name: 2-spaces-id-tweets
      path: /2/spaces/{id}/tweets
      operations:
      - name: getspacesposts
        method: GET
        description: X Get Space Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Space to be retrieved.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The number of Posts to fetch from the provided space. If not provided, the value will default to the
            maximum of 100.
    - name: 2-tweets
      path: /2/tweets
      operations:
      - name: getpostsbyids
        method: GET
        description: X Get Posts by IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: array
          description: A comma separated list of Post IDs. Up to 100 are allowed in a single request.
          required: true
      - name: createposts
        method: POST
        description: X Create or Edit Post
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-tweets-analytics
      path: /2/tweets/analytics
      operations:
      - name: getpostsanalytics
        method: GET
        description: X Get Post Analytics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: array
          description: A comma separated list of Post IDs. Up to 100 are allowed in a single request.
          required: true
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the end of the time range.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The UTC timestamp representing the start of the time range.
          required: true
        - name: granularity
          in: query
          type: string
          description: The granularity for the search counts results.
          required: true
    - name: 2-tweets-counts-all
      path: /2/tweets/counts/all
      operations:
      - name: getpostscountsall
        method: GET
        description: X Get Count of All Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query
            length.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is
            in second granularity and is inclusive (i.e. 12:00:01 include
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp
            is in second granularity and is exclusive (i.e. 12:00
        - name: since_id
          in: query
          type: string
          description: Returns results with a Post ID greater than (that is, more recent than) the specified ID.
        - name: until_id
          in: query
          type: string
          description: Returns results with a Post ID less than (that is, older than) the specified ID.
        - name: next_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: granularity
          in: query
          type: string
          description: The granularity for the search counts results.
    - name: 2-tweets-counts-recent
      path: /2/tweets/counts/recent
      operations:
      - name: getpostscountsrecent
        method: GET
        description: X Get Count of Recent Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query
            length.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp (from most recent 7 days) from which the Posts will
            be provided. Timestamp is in second granularity and is inclus
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp
            is in second granularity and is exclusive (i.e. 12:00
        - name: since_id
          in: query
          type: string
          description: Returns results with a Post ID greater than (that is, more recent than) the specified ID.
        - name: until_id
          in: query
          type: string
          description: Returns results with a Post ID less than (that is, older than) the specified ID.
        - name: next_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: granularity
          in: query
          type: string
          description: The granularity for the search counts results.
    - name: 2-tweets-firehose-stream
      path: /2/tweets/firehose/stream
      operations:
      - name: streampostsfirehose
        method: GET
        description: X Stream All Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-firehose-stream-lang-en
      path: /2/tweets/firehose/stream/lang/en
      operations:
      - name: streampostsfirehoseen
        method: GET
        description: X Stream English Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-firehose-stream-lang-ja
      path: /2/tweets/firehose/stream/lang/ja
      operations:
      - name: streampostsfirehoseja
        method: GET
        description: X Stream Japanese Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-firehose-stream-lang-ko
      path: /2/tweets/firehose/stream/lang/ko
      operations:
      - name: streampostsfirehoseko
        method: GET
        description: X Stream Korean Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-firehose-stream-lang-pt
      path: /2/tweets/firehose/stream/lang/pt
      operations:
      - name: streampostsfirehosept
        method: GET
        description: X Stream Portuguese Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-sample-stream
      path: /2/tweets/sample/stream
      operations:
      - name: streampostssample
        method: GET
        description: X Stream Sampled Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
    - name: 2-tweets-sample10-stream
      path: /2/tweets/sample10/stream
      operations:
      - name: streampostssample10
        method: GET
        description: X Stream 10% Sampled Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: partition
          in: query
          type: integer
          description: The partition number.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-search-all
      path: /2/tweets/search/all
      operations:
      - name: searchpostsall
        method: GET
        description: X Search All Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query
            length.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is
            in second granularity and is inclusive (i.e. 12:00:01 include
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp
            is in second granularity and is exclusive (i.e. 12:00
        - name: since_id
          in: query
          type: string
          description: Returns results with a Post ID greater than (that is, more recent than) the specified ID.
        - name: until_id
          in: query
          type: string
          description: Returns results with a Post ID less than (that is, older than) the specified ID.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of search results to be returned by a request.
        - name: next_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: sort_order
          in: query
          type: string
          description: This order in which to return results.
    - name: 2-tweets-search-recent
      path: /2/tweets/search/recent
      operations:
      - name: searchpostsrecent
        method: GET
        description: X Search Recent Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: One query/rule/filter for matching Posts. Refer to https://t.co/rulelength to identify the max query
            length.
          required: true
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The oldest UTC timestamp from which the Posts will be provided. Timestamp is
            in second granularity and is inclusive (i.e. 12:00:01 include
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The newest, most recent UTC timestamp to which the Posts will be provided. Timestamp
            is in second granularity and is exclusive (i.e. 12:00
        - name: since_id
          in: query
          type: string
          description: Returns results with a Post ID greater than (that is, more recent than) the specified ID.
        - name: until_id
          in: query
          type: string
          description: Returns results with a Post ID less than (that is, older than) the specified ID.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of search results to be returned by a request.
        - name: next_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results. The value used with the parameter is pulled
            directly from the response provided by the API, and should
        - name: sort_order
          in: query
          type: string
          description: This order in which to return results.
    - name: 2-tweets-search-stream
      path: /2/tweets/search/stream
      operations:
      - name: streamposts
        method: GET
        description: X Stream Filtered Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: backfill_minutes
          in: query
          type: integer
          description: The number of minutes of backfill requested.
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided.
        - name: end_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp to which the Posts will be provided.
    - name: 2-tweets-search-stream-rules
      path: /2/tweets/search/stream/rules
      operations:
      - name: getrules
        method: GET
        description: X Get Stream Rules
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: ids
          in: query
          type: array
          description: A comma-separated list of Rule IDs.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This value is populated by passing the 'next_token' returned in a request to paginate through results.
      - name: updaterules
        method: POST
        description: X Update Stream Rules
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: dry_run
          in: query
          type: boolean
          description: Dry Run can be used with both the add and delete action, with the expected result given, but without
            actually taking any action in the system (meaning the end s
        - name: delete_all
          in: query
          type: boolean
          description: Delete All can be used to delete all of the rules associated this client app, it should be specified
            with no other parameters. Once deleted, rules cannot be rec
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: 2-tweets-search-stream-rules-counts
      path: /2/tweets/search/stream/rules/counts
      operations:
      - name: getrulecounts
        method: GET
        description: X Get Stream Rule Counts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: 2-tweets-id
      path: /2/tweets/{id}
      operations:
      - name: deleteposts
        method: DELETE
        description: X Delete Post
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the Post to be deleted.
          required: true
      - name: getpostsbyid
        method: GET
        description: X Get Post by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A single Post ID.
          required: true
    - name: 2-tweets-id-liking_users
      path: /2/tweets/{id}/liking_users
      operations:
      - name: getpostslikingusers
        method: GET
        description: X Get Liking Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A single Post ID.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
    - name: 2-tweets-id-quote_tweets
      path: /2/tweets/{id}/quote_tweets
      operations:
      - name: getpostsquotedposts
        method: GET
        description: X Get Quoted Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A single Post ID.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results to be returned.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get a specified 'page' of results.
        - name: exclude
          in: query
          type: array
          description: The set of entities to exclude (e.g. 'replies' or 'retweets').
    - name: 2-tweets-id-retweeted_by
      path: /2/tweets/{id}/retweeted_by
      operations:
      - name: getpostsrepostedby
        method: GET
        description: X Get Reposted by
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A single Post ID.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
    - name: 2-tweets-id-retweets
      path: /2/tweets/{id}/retweets
      operations:
      - name: getpostsreposts
        method: GET
        description: X Get Reposts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A single Post ID.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
    - name: 2-tweets-tweet_id-hidden
      path: /2/tweets/{tweet_id}/hidden
      operations:
      - name: hidepostsreply
        method: PUT
        description: X Hide Reply
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: tweet_id
          in: path
          type: string
          description: The ID of the reply that you want to hide or unhide.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: 2-users-id-liked_tweets
      path: /2/users/{id}/liked_tweets
      operations:
      - name: getuserslikedposts
        method: GET
        description: X Get Liked Posts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the User to lookup.
          required: true
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
    - name: 2-users-id-likes
      path: /2/users/{id}/likes
      operations:
      - name: likepost
        method: POST
        description: X Like Post
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the authenticated source User that is requesting to like the Post.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: 2-users-id-likes-tweet_id
      path: /2/users/{id}/likes/{tweet_id}
      operations:
      - name: unlikepost
        method: DELETE
        description: X Unlike Post
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the authenticated source User that is requesting to unlike the Post.
          required: true
        - name: tweet_id
          in: path
          type: string
          description: The ID of the Post that the User is requesting to unlike.
          required: true
    - name: 2-users-id-mentions
      path: /2/users/{id}/mentions
      operations:
      - name: getusersmentions
        method: GET
        description: X Get Mentions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: The ID of the User to lookup.
          required: true
        - name: since_id
          in: query
          type: string
          description: The minimum Post ID to be included in the result set. This parameter takes precedence over start_time
            if both are specified.
        - name: until_id
          in: query
          type: string
          description: The maximum Post ID to be included in the result set. This parameter takes precedence over end_time
            if both are specified.
        - name: max_results
          in: query
          type: integer
          description: The maximum number of results.
        - name: pagination_token
          in: query
          type: string
          description: This parameter is used to get the next 'page' of results.
        - name: start_time
          in: query
          type: string
          description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Posts will be provided. The since_id
        

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/capabilities/x-tweets.yaml