Tweet Metadata, Profile & Media API Field Guide

Use this guide to get tweet metadata from Xquik responses. It maps Twitter API fields for tweets, user profiles, media files, and replies. Compare Twitter API user fields, Twitter profile fields, and media objects. Review tweet engagement metrics, quote context, repost context, and pagination. Quick answer: treat IDs as strings. Treat optional fields as conditional. Keep reply, quote, and repost relationships separate. Store a collection timestamp beside mutable engagement and profile counts. This Twitter metadata guide focuses on public fields X supplies. Xquik preserves every documented public field supplied for supported reads. Core fields remain stable. Optional fields appear only when X supplies them. The API reference defines exact REST and SDK types. Each API response must follow those documented types. The Twitter API response fields below match that public contract. The MCP contract normalizes names for agent use. Most fields use snake_case. REST createdAt becomes MCP created. It does not become created_at.

Choose the Object Before Mapping Fields

Need	Primary object	Stable join key
Tweet text and engagement	Tweet	`id`
Reply or thread relationship	Tweet	`conversationId` and `inReplyToId`
Quote context	`quoted_tweet`	Nested tweet `id`
Repost context	`retweeted_tweet`	Nested tweet `id`
Author profile	`author`	Author `id`
Image, video, or GIF	`media[]`	`mediaKey` or media `id`
Pagination	Page envelope	Returned cursor

Do not flatten every object into one unversioned row. Nested tweets and authors have their own IDs. Store those IDs before building joins.

Field Presence Rules

Required Fields

Tweet objects require id, text, and documented engagement counts. Profile objects require id, username, and name.

Optional Fields

Optional fields are omitted when X does not supply them. Absence is not an empty string, false value, or zero count.

String IDs

Keep tweet, user, media, conversation, and reply IDs as strings. Large IDs can lose precision in spreadsheet or JavaScript number types.

Count Snapshots

Likes, replies, reposts, quotes, views, bookmarks, followers, and following counts can change after collection. Store collected_at downstream.

A zero tweet metric can mean X did not report that count. Do not treat every zero as a measured absence.

Tweet Fields

Every tweet includes its ID, text, metrics, and available author profile. These optional fields preserve additional X metadata. Core tweet fields group into these roles:

Identity: id, type, url, createdAt, and lang
Publishing client: source
Text: text, displayTextRange, entities, and contentDisclosure
Reply state: isReply, isLimitedReply, and conversationId
Reply policy: conversationControl, limitedActions, and unmentionedUserIds
Reply targets: inReplyToId, inReplyToUserId, and inReplyToUsername
Quote state: isQuoteStatus and quoted_tweet
Quote ID: quotedTweetId
Repost context: retweeted_tweet
Long-form context: isNoteTweet
Related objects: author and media
Counts: retweetCount, replyCount, likeCount, and quoteCount
Reach: viewCount and bookmarkCount

Field	Description
`article`	X Article metadata
`card`	Link card metadata
`communityId`	Community ID
`communityNote`	Community Note metadata
`edit`	Edit history and remaining state
`isTranslatable`	Translation availability
`noteTweet`	Long-form post metadata
`place`	Tagged place metadata
`possiblySensitive`	X sensitivity state
`previousCounts`	Pre-edit engagement counts
`tombstone`	Unavailable tweet metadata
`viewState`	X view-state metadata

Tweets also include available entities, disclosures, nested tweets, and media.

Tweet Metadata Example

{
  "id": "1893704267862470862",
  "text": "A public tweet with a reply and media.",
  "createdAt": "2026-05-24T20:32:58.000Z",
  "url": "https://x.com/example/status/1893704267862470862",
  "lang": "en",
  "isReply": true,
  "isNoteTweet": false,
  "isQuoteStatus": false,
  "conversationId": "1893600000000000000",
  "inReplyToId": "1893690000000000000",
  "inReplyToUserId": "987654321",
  "inReplyToUsername": "parent_author",
  "retweetCount": 8,
  "replyCount": 3,
  "likeCount": 42,
  "quoteCount": 2,
  "viewCount": 1500,
  "bookmarkCount": 4,
  "author": {
    "id": "123456789",
    "username": "example",
    "name": "Example Account"
  },
  "media": [
    {
      "mediaUrl": "https://pbs.twimg.com/media/example.jpg",
      "type": "photo",
      "url": "https://x.com/example/status/1893704267862470862/photo/1",
      "altText": "Product dashboard with a tweet search result"
    }
  ]
}

The example illustrates field placement. Read the endpoint response for actual values. Never copy example IDs into a production join.

Map Replies, Quotes, and Reposts

Use isReply to identify a reply. Use inReplyToId for its direct parent. Use conversationId for the root conversation. These IDs can differ. Use isQuoteStatus to identify quote context. Read quoted_tweet for the nested quoted tweet when available. Keep the quoting tweet as its own row. Read retweeted_tweet for original repost context. Keep the returned outer tweet ID and nested tweet ID separate. This prevents incorrect engagement joins. Keep original tweets separate from outer repost records.

Direct Reply

Join inReplyToId to the parent tweet. Keep conversationId for the full thread.

Quote

Join quoted_tweet.id to the quoted tweet. Attribute quote text to the outer tweet.

Repost

Join retweeted_tweet.id to the original tweet. Do not merge their metric snapshots.

Note Tweet

Check isNoteTweet and noteTweet. Preserve long-form text and rich-text metadata when present.

Interpret Tweet Engagement Fields

likeCount, replyCount, retweetCount, quoteCount, viewCount, and bookmarkCount are count snapshots. They can change after collection. Store tweet_id, every count, and collected_at in one snapshot row. Compare snapshots with the same tweet ID. Do not overwrite history when measuring growth. previousCounts can preserve pre-edit engagement counts. edit can describe edit history. Keep both objects when analyzing edited tweets.

Map Entities and Content Labels

Read entities for URLs, mentions, hashtags, and other parsed text markers. Read displayTextRange before slicing rendered text. Preserve the original tweet text beside any normalized tokens. Read contentDisclosure for documented content labels. Read possiblySensitive for the returned sensitivity state. Never infer either field when it is absent.

Profile Fields

Every profile includes id, username, and name. Counts, verification, images, bios, and other metadata appear when X supplies them. Core profile fields group into these roles:

Identity: id, username, name, and createdAt
Bio: description, profile_bio, grokTranslatedBio, location, and url
Audience: followers and following
Activity: statusesCount, mediaCount, and favouritesCount
Verification: verified, isVerified, isBlueVerified, and verifiedType
Images: profilePicture, coverPicture, and profileBannerUrl
Access: protected, unavailable, and unavailableReason
Safety: possiblySensitive, withheldInCountries, and withheldScope
Automation: isAutomated and automatedBy
Features: hasCustomTimelines, isTranslator, and communityRole
Pinned content: pinnedTweetIds

Treat author as the user object for each returned tweet. Store the user profile using its stable id. A profile page can change its username, name, bio, and images. Keep pinned tweet IDs as strings.

Field	Description
`affiliatesHighlightedLabel`	Affiliate label metadata
`businessAccountAffiliatesCount`	Business affiliate count
`creatorSubscriptionsCount`	Creator subscription count
`professional`	Professional profile metadata
`hasGraduatedAccess`	Graduated access state
`hasHiddenSubscriptionsOnProfile`	Hidden subscription state
`highlightsInfo`	Profile highlights metadata
`identityVerification`	Identity verification metadata
`isProfileTranslatable`	Profile translation availability
`parodyCommentaryFanLabel`	Parody or fan label
`profileDescriptionLanguage`	Detected bio language
`profileImageShape`	Profile image shape
`profileInterstitialType`	Profile interstitial type
`profileSortEnabled`	Profile sorting state
`profileTranslatorType`	Profile translator type
`superFollowEligible`	Subscription eligibility
`superFollowsUserProfileActive`	Active subscription profile state
`tipJar`	Public creator support handles

Xquik removes account-specific actions, permissions, and relationships from public reads. Use dedicated write routes or X for account state.

Twitter Profile API Example

{
  "id": "9876543210",
  "username": "example_user",
  "name": "Example User",
  "description": "Developer building tweet monitoring tools.",
  "followers": 12500,
  "following": 420,
  "statusesCount": 8600,
  "mediaCount": 730,
  "verified": true,
  "isBlueVerified": false,
  "isVerified": true,
  "verifiedType": "Business",
  "profilePicture": "https://pbs.twimg.com/profile_images/example.jpg",
  "coverPicture": "https://pbs.twimg.com/profile_banners/example.jpg",
  "location": "London",
  "createdAt": "2018-04-12T10:30:00.000Z",
  "protected": false,
  "pinnedTweetIds": ["1893704267862470862"]
}

Use id as the profile join key. Usernames can change. Display names are not unique. Keep the observed username and collection time beside each snapshot.

Interpret Profile Counts

Use followers for the returned follower count. Use following for accounts the profile follows. Use statusesCount for the returned post count. Use mediaCount for posts containing media. Do not calculate follower growth from one response. Store dated profile snapshots. Compare the same X user ID across collection times.

Keep Verification Fields Separate

Preserve verified, isVerified, isBlueVerified, and verifiedType as distinct fields. X can return different verification signals. Do not collapse them into one custom boolean. identityVerification and affiliatesHighlightedLabel provide separate profile metadata. Preserve those objects when present.

Handle Protected or Unavailable Profiles

Use protected for the returned privacy state. Use unavailable and unavailableReason for unavailable profiles. Do not replace omitted profile fields with invented values. Keep withheldInCountries and possiblySensitive when returned. These fields describe public response state. They do not grant access to hidden content.

Media Fields

Media rows keep their URL and type. These optional fields add detail. The Twitter media API field section covers returned photos, videos, and GIFs. Store media files only when returned URLs and availability allow it. Every media object includes mediaUrl, type, and url.

Field	Description
`adultContent`	Adult content state
`allowDownload`	Download permission
`altText`	Accessibility text
`aspectRatio`	Video aspect ratio
`availabilityStatus`	Media availability state
`availabilityReason`	Media availability reason
`description`	Media description
`displayUrl`	Display URL
`durationMillis`	Video duration
`embeddable`	Embedding availability
`expandedUrl`	Expanded media URL
`faceRects`	Detected face rectangles
`focusRects`	Crop focus rectangles
`grokPostId`	Related Grok post ID
`height`	Media height
`id`	Media ID
`indices`	Source-text indices
`mediaKey`	X media key
`monetizable`	Monetization state
`sizes`	Available image sizes
`sourceStatusId`	Source tweet ID
`sourceUserId`	Source user ID
`tags`	Tagged users
`title`	Media title
`videoVariants`	Video encodings and bitrates
`visitSiteUrl`	Public destination URL
`watchNowUrl`	Public media action URL
`width`	Media width

Map Photos, Videos, and GIFs

Read type before selecting a media workflow. Supported values are photo, video, and animated_gif. Keep the original type with every media row. Use mediaUrl as the returned preview URL. Use url as the X media link. Use expandedUrl and displayUrl only when present. Preserve altText for accessibility. Preserve width, height, and aspectRatio for layout. Preserve durationMillis for video duration. videoVariants can contain multiple encodings and bitrates. Keep the complete array when another service selects playback quality. Do not invent a missing variant. Use allowDownload and availabilityStatus when returned. Check both before a media handoff. A media object does not guarantee permanent file availability.

Store a Media Join Row

{
  "tweet_id": "1893704267862470862",
  "media_id": "1912345678901234567",
  "media_key": "3_1912345678901234567",
  "media_type": "video",
  "media_url": "https://pbs.twimg.com/ext_tw_video_thumb/example.jpg",
  "x_media_url": "https://x.com/example/status/1893704267862470862/video/1",
  "duration_millis": 18400,
  "alt_text": "Short product demonstration",
  "collected_at": "2026-05-24T20:33:00.000Z"
}

Create one row per media object. Join it back through tweet_id. Keep all variants in a child table or structured column.

Reply Coverage

Reply coverage depends on X. X can hide, rank, or omit counted replies. Omit mode for automatic maximum direct-reply coverage with pagination. Pass each next_cursor back unchanged as cursor. This keeps the standard response shape and billing. Use GET /api/v1/x/tweets/<tweet_id>/replies?mode=complete&limit=25000. Complete mode adds nested replies and detailed diagnostics. Direct replies match inReplyToId to the requested tweet. Keep nested_replies separate. Trust diagnostic.complete instead of row count. Complete mode requires 80% of X’s current reported direct replies. HTTP 424 replies_incomplete returns the collected rows and coverage diagnostic. Inspect coveragePercentage, strategy results, cursor failures, and fallback. Disclose that reply coverage depends on X.

Store Reply Relationships

Keep these fields for each collected reply:

id for the reply tweet
inReplyToId for the direct parent
conversationId for the thread root
author.id for the reply author
createdAt for ordering
nested_replies for separately returned descendants

Do not infer a direct parent from array position. Use inReplyToId. Keep nested_replies separate from direct replies when measuring first-level coverage.

Twitter API Pagination Fields

Tweet, profile, follower, reply, list, and timeline routes can return page envelopes. Keep each endpoint’s documented field names. REST read pages commonly return has_next_page and next_cursor. Pass the returned cursor back as cursor. Stop when has_next_page is false. Extraction result pages return hasMore and nextCursor. Pass nextCursor back as cursor. Do not mix REST cursors with extraction cursors. Commit rows and their next cursor together. A retry must upsert by tweet ID, user ID, or media ID before advancing.

Field Mapping Handoff

{
  "schema": "xquik.tweet_profile_fields.v1",
  "source_route": "GET /api/v1/x/tweets/1893704267862470862",
  "tweet_key": "id",
  "profile_key": "author.id",
  "media_key": "media[].mediaKey",
  "reply_parent_key": "inReplyToId",
  "conversation_key": "conversationId",
  "quote_key": "quoted_tweet.id",
  "repost_key": "retweeted_tweet.id",
  "count_fields": [
    "likeCount",
    "replyCount",
    "retweetCount",
    "quoteCount",
    "viewCount",
    "bookmarkCount"
  ],
  "ids_as_strings": true,
  "optional_field_policy": "preserve_absence",
  "collected_at": "2026-05-24T20:33:00.000Z"
}

Use this checkpoint when building CSV, warehouse, search-index, or CRM rows. Keep nested JSON when flattening would erase relationships.

Surface Mapping

Surface	Field style	Contract
REST API	Mostly `camelCase`	`quoted_tweet`, `retweeted_tweet`, and `profile_bio` are documented exceptions
Generated SDKs	Language-native names	Generated OpenAPI models
MCP	Normalized	Most names use `snake_case`; REST `createdAt` becomes MCP `created`
Apify Actors	Configurable	Dataset schemas and Actor READMEs

Xquik omits unavailable optional fields. It never invents missing X values.

Keep Surface Names Explicit

Do not assume one casing rule covers every field. REST uses mostly camel case. The documented nested exceptions keep their public names. Generated SDKs expose language-native models from OpenAPI. Use the generated property names for that SDK version. Do not hand-convert them from REST. MCP tools normalize most response names for agents. REST createdAt becomes MCP created. Actor datasets follow each Actor’s documented output mode.

Avoid Tweet Metadata Mapping Errors

Large IDs become rounded numbers

Precision lost. Store tweet, user, conversation, reply, and media IDs as strings before spreadsheet or JavaScript processing.

Missing optional fields become false or zero

Meaning changed. Preserve field absence. Add a separate downstream default only when the consumer requires one.

Reply and conversation IDs are merged

Relationship lost. Keep inReplyToId for the parent. Keep conversationId for the root.

Quote and repost metrics are combined

Counts misattributed. Keep outer and nested tweet IDs in separate rows.

Profile growth uses usernames as keys

History split. Use the stable X user ID. Store the observed username as an attribute.

Tweet Metadata and Profile API Questions

How Do I Get Tweet Metadata?

Call the route matching your tweet, timeline, profile, or reply task. Read the returned API response through its documented schema. Keep IDs, counts, relationships, and cursors without inventing missing fields.

Which Twitter API Fields Should I Store?

Start with IDs, text, timestamps, authors, engagement counts, media, and relationships. Add optional fields only when X supplies them. Store collection time beside mutable counts.

Which Twitter API User Fields Identify a Profile?

Use id as the stable profile key. Keep username, name, bio, images, verification, followers, and following. Record collection time beside changing profile counts.

How Do I Read Twitter API Response Fields?

Follow each Xquik route’s response schema in the API reference. Use the field names documented for each surface. Apply only documented mappings between REST, SDK, MCP, and Actor names.

How Do I Read Twitter API Pagination Fields?

Twitter API pagination uses the response envelope documented for each route. Read has_next_page with next_cursor for REST pages. Read hasMore with nextCursor for extraction result pages. Never mix cursors between those response envelopes.

What Metadata Does a Tweet Include?

A tweet includes its ID, text, counts, URL, language, and relationship fields. It can also include author, media, entities, labels, and edit objects. Article, place, quote, repost, and Note Tweet objects can also appear.

How Do I Find a Tweet ID?

Read the response id field. Keep it as a string. Use it for lookups, joins, dedupe, exports, and engagement snapshots.

What Is a Twitter Conversation ID?

conversationId identifies the root tweet for the returned conversation. inReplyToId identifies one reply’s direct parent. Preserve both fields.

How Do I Know Whether a Tweet Is a Reply?

Check isReply. Then read inReplyToId, inReplyToUserId, and inReplyToUsername when present.

How Do Quotes Differ From Reposts?

Quotes can add new outer tweet text and quoted_tweet context. Reposts expose original context through retweeted_tweet. Keep both tweet IDs separate.

Which Fields Contain Twitter Engagement Metrics?

Use likeCount, replyCount, retweetCount, quoteCount, viewCount, and bookmarkCount. Store collection time because these counts can change.

Does the Twitter Profile API Include Follower Counts?

Yes. Read followers and following when supplied. Store dated snapshots for growth tracking. Join snapshots through the profile id.

Why Is a Tweet or Profile Field Missing?

The field is optional and X did not supply it for that response. Preserve the absence. Never replace it with an invented value.

How Do I Get Tweet Media Metadata?

Read the tweet’s media array. Use type, URLs, dimensions, alt text, duration, availability, and video variants when present.

Can I Export Tweet Metadata to CSV?

Yes. Flatten selected scalar fields and keep stable IDs. Store nested author, media, quote, and repost objects separately. Use linked rows or JSON columns.

Do REST, SDK, MCP, and Actor Fields Match Exactly?

They share the documented contract but can expose different field naming. Follow the OpenAPI model, MCP response shape, or Actor dataset schema directly.

​Choose the Object Before Mapping Fields

​Field Presence Rules

Required Fields

Optional Fields

String IDs

Count Snapshots

​Tweet Fields

​Tweet Metadata Example

​Map Replies, Quotes, and Reposts

Direct Reply

Quote

Repost

Note Tweet

​Interpret Tweet Engagement Fields

​Map Entities and Content Labels

​Profile Fields

​Twitter Profile API Example

​Interpret Profile Counts

​Keep Verification Fields Separate

​Handle Protected or Unavailable Profiles

​Media Fields

​Map Photos, Videos, and GIFs

​Store a Media Join Row

​Reply Coverage

​Store Reply Relationships

​Twitter API Pagination Fields

​Field Mapping Handoff

​Surface Mapping

​Keep Surface Names Explicit

​Avoid Tweet Metadata Mapping Errors

​Tweet Metadata and Profile API Questions

​How Do I Get Tweet Metadata?

​Which Twitter API Fields Should I Store?

​Which Twitter API User Fields Identify a Profile?

​How Do I Read Twitter API Response Fields?

​How Do I Read Twitter API Pagination Fields?

​What Metadata Does a Tweet Include?

​How Do I Find a Tweet ID?

​What Is a Twitter Conversation ID?

​How Do I Know Whether a Tweet Is a Reply?

​How Do Quotes Differ From Reposts?

​Which Fields Contain Twitter Engagement Metrics?

​Does the Twitter Profile API Include Follower Counts?

​Why Is a Tweet or Profile Field Missing?

​How Do I Get Tweet Media Metadata?

​Can I Export Tweet Metadata to CSV?

​Do REST, SDK, MCP, and Actor Fields Match Exactly?

Choose the Object Before Mapping Fields

Field Presence Rules

Tweet Fields

Tweet Metadata Example

Map Replies, Quotes, and Reposts

Interpret Tweet Engagement Fields

Map Entities and Content Labels

Profile Fields

Twitter Profile API Example

Interpret Profile Counts

Keep Verification Fields Separate

Handle Protected or Unavailable Profiles

Media Fields

Map Photos, Videos, and GIFs

Store a Media Join Row

Reply Coverage

Store Reply Relationships

Twitter API Pagination Fields

Field Mapping Handoff

Surface Mapping

Keep Surface Names Explicit

Avoid Tweet Metadata Mapping Errors

Tweet Metadata and Profile API Questions

How Do I Get Tweet Metadata?

Which Twitter API Fields Should I Store?

Which Twitter API User Fields Identify a Profile?

How Do I Read Twitter API Response Fields?

How Do I Read Twitter API Pagination Fields?

What Metadata Does a Tweet Include?

How Do I Find a Tweet ID?

What Is a Twitter Conversation ID?

How Do I Know Whether a Tweet Is a Reply?

How Do Quotes Differ From Reposts?

Which Fields Contain Twitter Engagement Metrics?

Does the Twitter Profile API Include Follower Counts?

Why Is a Tweet or Profile Field Missing?

How Do I Get Tweet Media Metadata?

Can I Export Tweet Metadata to CSV?

Do REST, SDK, MCP, and Actor Fields Match Exactly?