X (Twitter) · JSON Structure

X Api Tweet Structure

Tweet schema from X API v2

Type: object Properties: 29
Social MediaMicrobloggingReal-Time DataStreamingAdvertisingContent

Tweet is a JSON Structure definition published by X (Twitter), describing 29 properties. It conforms to the https://json-structure.org/meta/core/v0/# meta-schema.

Properties

attachments author_id community_id context_annotations conversation_id created_at display_text_range edit_controls edit_history_tweet_ids entities geo id in_reply_to_user_id lang non_public_metrics note_tweet organic_metrics possibly_sensitive promoted_metrics public_metrics referenced_tweets reply_settings scopes source suggested_source_links suggested_source_links_with_counts text username withheld

Meta-schema: https://json-structure.org/meta/core/v0/#

JSON Structure

Raw ↑ 
{
  "$schema": "https://json-structure.org/meta/core/v0/#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/json-structure/x-api-tweet-structure.json",
  "name": "Tweet",
  "description": "Tweet schema from X API v2",
  "type": "object",
  "properties": {
    "attachments": {
      "type": "object",
      "description": "Specifies the type of attachments (if any) present in this Tweet.",
      "properties": {
        "media_keys": {
          "type": "array",
          "description": "A list of Media Keys for each one of the media attachments (if media are attached).",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/MediaKey"
          }
        },
        "media_source_tweet_id": {
          "type": "array",
          "description": "A list of Posts the media on this Tweet was originally posted in. For example, if the media on a tweet is re-used in another Tweet, this refers to the original, source Tweet..",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/TweetId"
          }
        },
        "poll_ids": {
          "type": "array",
          "description": "A list of poll IDs (if polls are attached).",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/PollId"
          }
        }
      }
    },
    "author_id": {
      "type": "string",
      "description": "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.",
      "pattern": "^[0-9]{1,19}$",
      "example": "2244994945"
    },
    "community_id": {
      "type": "string",
      "description": "The unique identifier of this Community.",
      "pattern": "^[0-9]{1,19}$",
      "example": "1146654567674912769"
    },
    "context_annotations": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/components/schemas/ContextAnnotation"
      }
    },
    "conversation_id": {
      "type": "string",
      "description": "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.",
      "pattern": "^[0-9]{1,19}$",
      "example": "1346889436626259968"
    },
    "created_at": {
      "type": "datetime",
      "description": "Creation time of the Tweet.",
      "example": "2021-01-06T18:40:40.000Z"
    },
    "display_text_range": {
      "type": "array",
      "description": "Represent a boundary range (start and end zero-based indices) for the portion of text that is displayed for a post. `start` must be smaller than `end`. The start index is inclusive, the end index is exclusive.",
      "minItems": 2,
      "maxItems": 2,
      "items": {
        "type": "int32",
        "minimum": 0
      }
    },
    "edit_controls": {
      "type": "object",
      "required": [
        "is_edit_eligible",
        "editable_until",
        "edits_remaining"
      ],
      "properties": {
        "editable_until": {
          "type": "datetime",
          "description": "Time when Tweet is no longer editable.",
          "example": "2021-01-06T18:40:40.000Z"
        },
        "edits_remaining": {
          "type": "int32",
          "description": "Number of times this Tweet can be edited."
        },
        "is_edit_eligible": {
          "type": "boolean",
          "description": "Indicates if this Tweet is eligible to be edited.",
          "example": false
        }
      }
    },
    "edit_history_tweet_ids": {
      "type": "array",
      "description": "A list of Tweet Ids in this Tweet chain.",
      "minItems": 1,
      "items": {
        "$ref": "#/components/schemas/TweetId"
      }
    },
    "entities": {
      "type": "object",
      "properties": {
        "annotations": {
          "type": "array",
          "minItems": 1,
          "items": {
            "description": "Annotation for entities based on the Tweet text.",
            "allOf": [
              {
                "$ref": "#/components/schemas/EntityIndicesInclusiveInclusive"
              },
              {
                "type": "object",
                "description": "Represents the data for the annotation.",
                "properties": {
                  "normalized_text": {
                    "type": "string",
                    "description": "Text used to determine annotation.",
                    "example": "Barack Obama"
                  },
                  "probability": {
                    "type": "double",
                    "description": "Confidence factor for annotation type.",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "type": {
                    "type": "string",
                    "description": "Annotation type.",
                    "example": "Person"
                  }
                }
              }
            ]
          }
        },
        "cashtags": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/CashtagEntity"
          }
        },
        "hashtags": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/HashtagEntity"
          }
        },
        "mentions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/MentionEntity"
          }
        },
        "urls": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/UrlEntity"
          }
        }
      }
    },
    "geo": {
      "type": "object",
      "description": "The location tagged on the Tweet, if the user provided one.",
      "properties": {
        "coordinates": {
          "$ref": "#/components/schemas/Point"
        },
        "place_id": {
          "$ref": "#/components/schemas/PlaceId"
        }
      }
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.",
      "pattern": "^[0-9]{1,19}$",
      "example": "1346889436626259968"
    },
    "in_reply_to_user_id": {
      "type": "string",
      "description": "Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.",
      "pattern": "^[0-9]{1,19}$",
      "example": "2244994945"
    },
    "lang": {
      "type": "string",
      "description": "Language of the Tweet, if detected by X. Returned as a BCP47 language tag.",
      "example": "en"
    },
    "non_public_metrics": {
      "type": "object",
      "description": "Nonpublic engagement metrics for the Tweet at the time of the request.",
      "properties": {
        "impression_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been viewed."
        }
      }
    },
    "note_tweet": {
      "type": "object",
      "description": "The full-content of the Tweet, including text beyond 280 characters.",
      "properties": {
        "entities": {
          "type": "object",
          "properties": {
            "cashtags": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/CashtagEntity"
              }
            },
            "hashtags": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/HashtagEntity"
              }
            },
            "mentions": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/MentionEntity"
              }
            },
            "urls": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/UrlEntity"
              }
            }
          }
        },
        "text": {
          "$ref": "#/components/schemas/NoteTweetText"
        }
      }
    },
    "organic_metrics": {
      "type": "object",
      "description": "Organic nonpublic engagement metrics for the Tweet at the time of the request.",
      "required": [
        "impression_count",
        "retweet_count",
        "reply_count",
        "like_count"
      ],
      "properties": {
        "impression_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been viewed."
        },
        "like_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been liked."
        },
        "reply_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been replied to."
        },
        "retweet_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been Retweeted."
        }
      }
    },
    "possibly_sensitive": {
      "type": "boolean",
      "description": "Indicates if this Tweet contains URLs marked as sensitive, for example content suitable for mature audiences.",
      "example": false
    },
    "promoted_metrics": {
      "type": "object",
      "description": "Promoted nonpublic engagement metrics for the Tweet at the time of the request.",
      "properties": {
        "impression_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been viewed."
        },
        "like_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been liked."
        },
        "reply_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been replied to."
        },
        "retweet_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been Retweeted."
        }
      }
    },
    "public_metrics": {
      "type": "object",
      "description": "Engagement metrics for the Tweet at the time of the request.",
      "required": [
        "retweet_count",
        "reply_count",
        "like_count",
        "impression_count",
        "bookmark_count"
      ],
      "properties": {
        "bookmark_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been bookmarked."
        },
        "impression_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been viewed."
        },
        "like_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been liked."
        },
        "quote_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been quoted."
        },
        "reply_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been replied to."
        },
        "retweet_count": {
          "type": "int32",
          "description": "Number of times this Tweet has been Retweeted."
        }
      }
    },
    "referenced_tweets": {
      "type": "array",
      "description": "A list of Posts this Tweet refers to. For example, if the parent Tweet is a Retweet, a Quoted Tweet or a Reply, it will include the related Tweet referenced to by its parent.",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/TweetId"
          },
          "type": {
            "type": "string",
            "enum": [
              "retweeted",
              "quoted",
              "replied_to"
            ]
          }
        }
      }
    },
    "reply_settings": {
      "type": "string",
      "description": "Shows who can reply a Tweet. Fields returned are everyone, mentioned_users, subscribers, verified and following.",
      "pattern": "^[A-Za-z]{1,12}$",
      "enum": [
        "everyone",
        "mentionedUsers",
        "following",
        "other",
        "subscribers",
        "verified"
      ]
    },
    "scopes": {
      "type": "object",
      "description": "The scopes for this tweet",
      "properties": {
        "followers": {
          "type": "boolean",
          "description": "Indicates if this Tweet is viewable by followers without the Tweet ID",
          "example": false
        }
      }
    },
    "source": {
      "type": "string",
      "description": "This is deprecated."
    },
    "suggested_source_links": {
      "type": "array",
      "minItems": 0,
      "items": {
        "$ref": "#/components/schemas/UrlEntity"
      }
    },
    "suggested_source_links_with_counts": {
      "type": "object",
      "description": "Suggested source links and the number of requests that included each link.",
      "properties": {
        "count": {
          "type": "int32",
          "description": "Number of note requests that included the source link."
        },
        "url": {
          "$ref": "#/components/schemas/UrlEntity"
        }
      }
    },
    "text": {
      "type": "string",
      "description": "The content of the Tweet.",
      "example": "Learn how to use the user Tweet timeline and user mention timeline endpoints in the X API v2 to explore Tweet\\u2026 https:\\/\\/t.co\\/56a0vZUx7i"
    },
    "username": {
      "type": "string",
      "description": "The X handle (screen name) of this user.",
      "pattern": "^[A-Za-z0-9_]{1,15}$"
    },
    "withheld": {
      "type": "object",
      "description": "Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country).",
      "required": [
        "copyright",
        "country_codes"
      ],
      "properties": {
        "copyright": {
          "type": "boolean",
          "description": "Indicates if the content is being withheld for on the basis of copyright infringement."
        },
        "country_codes": {
          "type": "array",
          "description": "Provides a list of countries where this content is not available.",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "$ref": "#/components/schemas/CountryCode"
          }
        },
        "scope": {
          "type": "string",
          "description": "Indicates whether the content being withheld is the `tweet` or a `user`.",
          "enum": [
            "tweet",
            "user"
          ]
        }
      }
    }
  }
}