Data Models

This page describes the data structures returned by the XScraper API.

Profile

The Profile object contains information about a Twitter user.

Profile

interface Profile {
  avatar?: string;
  banner?: string;
  biography?: string;
  birthday?: string;
  followersCount?: number;
  followingCount?: number;
  friendsCount?: number;
  mediaCount?: number;
  statusesCount?: number;
  isPrivate?: boolean;
  isVerified?: boolean;
  isBlueVerified?: boolean;
  joined?: Date;
  likesCount?: number;
  listedCount?: number;
  location: string;
  name?: string;
  pinnedTweetIds?: string[];
  tweetsCount?: number;
  url?: string;
  userId?: string;
  username?: string;
  website?: string;
  canDm?: boolean;
}

The Tweet object contains information about a Twitter tweet.

interface Tweet {
  bookmarkCount?: number;
  conversationId?: string;
  hashtags: string[];
  html?: string;
  id?: string;
  inReplyToStatus?: Tweet;
  inReplyToStatusId?: string;
  isQuoted?: boolean;
  isPin?: boolean;
  isReply?: boolean;
  isRetweet?: boolean;
  isSelfThread?: boolean;
  likes?: number;
  name?: string;
  mentions: Mention[];
  permanentUrl?: string;
  photos: Photo[];
  place?: PlaceRaw;
  quotedStatus?: Tweet;
  quotedStatusId?: string;
  replies?: number;
  retweets?: number;
  retweetedStatus?: Tweet;
  retweetedStatusId?: string;
  text?: string;
  thread: Tweet[];
  timeParsed?: Date;
  timestamp?: number;
  urls: string[];
  userId?: string;
  username?: string;
  videos: Video[];
  views?: number;
  sensitiveContent?: boolean;
  poll?: PollV2 | null;
}

Mention

The Mention object contains information about a user mentioned in a tweet.

Mention

interface Mention {
  id: string;
  username?: string;
  name?: string;
}

Photo

The Photo object contains information about a photo attached to a tweet.

Photo

interface Photo {
  id: string;
  url: string;
  alt_text: string | undefined;
}

Video

The Video object contains information about a video attached to a tweet.

Video

interface Video {
  id: string;
  preview: string;
  url?: string;
}

Place

The Place object contains information about a location tagged in a tweet.

Place

interface PlaceRaw {
  id?: string;
  place_type?: string;
  name?: string;
  full_name?: string;
  country_code?: string;
  country?: string;
  bounding_box?: {
    type?: string;
    coordinates?: number[][][];
  };
}

Poll

The Poll object contains information about a poll attached to a tweet.

Poll

interface PollData {
  id?: string;
  end_datetime?: string;
  voting_status?: string;
  duration_minutes: number;
  options: PollOption[];
}

interface PollOption {
  position?: number;
  label: string;
  votes?: number;
}

Response Formats

The API returns data in the following formats:

Success Response

{
  "data": {
    // Response data here
  },
  "meta": {
    "statusCode": 200, // HTTP status code
    "timestamp": "2025-04-19T15:49:28.824Z" // Response timestamp
  }
}

Error Response

{
  "statusCode": 401, // HTTP status code
  "timestamp": "2025-04-19T15:49:28.824Z", // Response timestamp
  "path": "/api/v1/twitter/users/following/154800500438809805", // Request path
  "method": "GET", // HTTP method
  "message": "Invalid or expired API key" // Error message
}

Paginated Responses

Some endpoints return paginated results with next/previous cursors:

QueryTweetsResponse

interface QueryTweetsResponse {
  tweets: Tweet[];
  next?: string; // Cursor for the next page
  previous?: string; // Cursor for the previous page
}

QueryProfilesResponse

interface QueryProfilesResponse {
  profiles: Profile[];
  next?: string; // Cursor for the next page
  previous?: string; // Cursor for the previous page
}