X (Twitter) API Object Reference: Tweet and User Fields

Every response from the X API v2 is built from a small set of objects: the Post (still called a Tweet in most field names), the User, and the Media, Poll and Place objects that hang off them. This reference lists every field on each, with its type, what it actually contains, the authentication it needs, and the nested keys and enum values that the official one-line descriptions leave out.

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.

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