Field names, types and descriptions are taken from X's own v2 data dictionary, the fields guide and the expansions guide, read on 30 August 2026.

TL;DR: A post lookup returns only id, text and edit_history_tweet_ids unless you ask for more with tweet.fields. Ids are strings, not numbers, on purpose. public_metrics is readable with app-only auth; the non_public_metrics, organic_metrics and promoted_metrics objects need user context and only work on the authenticated user's own posts. Related objects such as the author or attached media are never nested inside a post; they arrive in a separate includes block that you join on id.

What Is the X API Tweet Object?

The X API tweet object, called a Post in X's current vocabulary, is the JSON record v2 returns for a single post. By default it carries three fields. Up to 29 top-level fields are available on request, several of them objects with their own keys, and it links to the author, referenced posts, media, polls and places by id rather than embedding them.

How Fields Work

The v2 API returns a minimal object by default and expects you to opt in to everything else. Each object type has its own query parameter:

A request for a post with engagement counts and a timestamp therefore looks like ?tweet.fields=created_at,public_metrics,author_id. Omit the parameter and those keys are simply absent from the response, which is the single most common cause of "the API is not returning X" questions.

Post (Tweet) Object Fields

Auth column: app means readable with an app-only bearer token; user means the request needs user-context OAuth, and for the three private metric objects, the authenticated user must be the post's author.

Nested keys inside public_metrics and the private metric objects

All metric values are captured at the time of the request. They are not monotonic and not live: two reads seconds apart can differ, and a stored count from last week is not corrected by reading again.

Nested keys inside entities, referenced_tweets, attachments and geo

entities.urls[].url is always the t.co wrapper. The address a human would recognise is expanded_url, and if X followed a further redirect, unwound_url. Code that indexes links by url ends up with a table of t.co strings.

User Object Fields

Enum values on the user object

Media, Poll and Place Objects

These never appear at the top level. They arrive in includes.media, includes.polls and includes.places when the matching expansion is requested, and you join them to the post on media_key, poll id or place id.

Media

A video's downloadable file is never in url. It is one of the entries in variants, usually the highest bit_rate with content_type of video/mp4.

Poll

Place

Expansions: Pulling Related Objects Into the Same Response

An expansion asks X to include the object behind an id field. The post keeps the id; the object lands in includes.

Expansions and fields compose. expansions=author_id&user.fields=public_metrics returns the author in includes.users with follower counts; without the user.fields part the included user carries only id, name and username.

The Fields Most Code Gets Wrong

How These Fields Map on a Managed API

A managed provider that returns denormalised responses removes the fields-and-expansions step: the author, counts and media arrive inline on every post, with no tweet.fields, expansions or includes join to write. The vocabulary shifts to camelCase, so the mapping is worth having in one place. On GetXAPI, the correspondence for the fields most pipelines depend on is:

The shape is documented per endpoint in the GetXAPI API reference, for example tweet detail and user info. Reads are billed per call at $0.001, with a standard call returning about 20 posts, and there is no developer account or approval step before the first request.

Frequently Asked Questions

What fields does the X API return by default for a tweet?

Three: id, text and edit_history_tweet_ids. Everything else, including created_at, author_id and public_metrics, has to be requested explicitly with the tweet.fields parameter. A lookup that omits tweet.fields returns exactly those three keys and nothing more.

What is inside public_metrics on a tweet?

Six counters: retweet_count, reply_count, like_count, quote_count, bookmark_count and impression_count. They are point-in-time values captured when the request was served, not live counters, so two requests seconds apart can disagree. Everything in public_metrics is readable with app-only auth.

Why is the tweet id a string and not a number?

Tweet and user ids are 64-bit integers that exceed the 53-bit safe integer range of JavaScript and of any JSON parser that decodes numbers as doubles. X serialises them as strings so they survive the round trip. Parse them as strings and compare them as strings; converting to a float silently corrupts the low digits.

What is the difference between verified and verified_type on a user?

verified is a boolean that says whether the account currently carries a checkmark of any kind. verified_type says which kind: blue for an X Premium subscriber, business for an organisation, government for a state account. Since paid verification launched, verified: true no longer implies the legacy notability check, so code that treats it as a trust signal needs verified_type as well.

How do I get the author of a tweet in the same response?

Ask for the expansion. author_id on the post is only an id; adding expansions=author_id makes X return the matching User object in a separate includes.users array, keyed by that id. The user is not nested inside the post, so your code has to join the two arrays on the id.

Related Reading

• X API error codes reference, what comes back when a request fails instead of returning these objects
• Twitter advanced search operators, the query side that produces these objects in bulk
• Twitter API rate limits, how many of these responses you can pull per window
• Python Twitter API tutorial, parsing these fields in practice

Originally published on getxapi.com, where the reference is kept current as X changes the objects.