Twitter / X

Twitter: tweets, users, handles, and search. All endpoints are read-only GET requests and return public Twitter/X data — no posting or account access is included.

Base URL: https://api.pullbay.com/

Endpoints

Endpoint	Description	Pagination
GET /twitter/search	Search tweets by query	Cursor / maxItems
GET /twitter/tweet/{id}	Get a single tweet by ID	—
GET /twitter/handle/{handle}	Get a user by handle	—
GET /twitter/handle/{handle}/about	Get a user's about/bio details by handle	—
GET /twitter/user/{id}	Get a user by numeric ID	—
GET /twitter/user/{id}/tweets	Get tweets posted by a user	Cursor / maxItems

---

Search Twitter

Search tweets matching a query.

Request

GET /twitter/search
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query, 1–100 characters
sort	string	No	Top or Latest (default Latest)
useFirst	string	No	true or false (default false)
cursor	string	No	Pagination cursor from a previous response. Mutually exclusive with maxItems
maxItems	integer	No	One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

Example

curl -G "https://api.pullbay.com/twitter/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="openai" \
  -d sort=Latest \
  -d maxItems=20

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "tweet",
      "id": "20",
      "url": "https://x.com/jack/status/20",
      "twitterUrl": "https://twitter.com/jack/status/20",
      "text": "just setting up my twttr",
      "fullText": "just setting up my twttr",
      "source": "Twitter Web Client",
      "lang": "en",
      "createdAt": "Tue Mar 21 20:50:14 +0000 2006",
      "conversationId": "20",
      "retweetCount": 126541,
      "replyCount": 17858,
      "likeCount": 309719,
      "quoteCount": 6384,
      "bookmarkCount": 21386,
      "viewCount": null,
      "isReply": false,
      "isPinned": false,
      "isRetweet": false,
      "isQuote": false,
      "author": {
        "type": "user",
        "id": "44196397",
        "userName": "elonmusk",
        "name": "Elon Musk",
        "url": "https://x.com/elonmusk",
        "twitterUrl": "https://twitter.com/elonmusk",
        "description": "https://t.co/dDtDyVssfm",
        "location": "",
        "profilePicture": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_normal.jpg",
        "coverPicture": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
        "isVerified": true,
        "isBlueVerified": true,
        "protected": false,
        "canDm": false,
        "canMediaTag": false,
        "followers": 239698341,
        "following": 1319,
        "fastFollowersCount": 0,
        "favouritesCount": 225074,
        "listedCount": 168631,
        "mediaCount": 4467,
        "statusesCount": 101980,
        "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
        "status": ""
      },
      "media": []
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "DAACCgACGY...", "offset": null },
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged. Using maxItems to pull more results in one call costs proportionally more than a single page.

---

Get Tweet

Returns a single tweet by its numeric ID.

Request

GET /twitter/tweet/{id}
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
id	string	Yes	Numeric tweet ID, 1–100 characters (e.g. 20)

Example

curl -G "https://api.pullbay.com/twitter/tweet/20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "tweet",
      "id": "20",
      "url": "https://x.com/jack/status/20",
      "twitterUrl": "https://twitter.com/jack/status/20",
      "text": "just setting up my twttr",
      "fullText": "just setting up my twttr",
      "source": "Twitter Web Client",
      "lang": "en",
      "createdAt": "Tue Mar 21 20:50:14 +0000 2006",
      "conversationId": "20",
      "retweetCount": 126541,
      "replyCount": 17858,
      "likeCount": 309719,
      "quoteCount": 6384,
      "bookmarkCount": 21386,
      "viewCount": null,
      "isReply": false,
      "isPinned": false,
      "isRetweet": false,
      "isQuote": false,
      "author": {
        "type": "user",
        "id": "12",
        "userName": "jack",
        "name": "jack",
        "url": "https://x.com/jack",
        "twitterUrl": "https://twitter.com/jack",
        "description": "",
        "location": "",
        "profilePicture": "https://pbs.twimg.com/profile_images/1115644092329758721/AFjOzXz3_normal.jpg",
        "coverPicture": "",
        "isVerified": false,
        "isBlueVerified": false,
        "protected": false,
        "canDm": false,
        "canMediaTag": false,
        "followers": 6800000,
        "following": 4500,
        "fastFollowersCount": 0,
        "favouritesCount": 25000,
        "listedCount": 22000,
        "mediaCount": 350,
        "statusesCount": 30000,
        "createdAt": "Tue Mar 21 20:50:14 +0000 2006",
        "status": ""
      },
      "media": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged.

---

Get User By Handle

Returns a Twitter user by handle (without @).

Request

GET /twitter/handle/{handle}
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
handle	string	Yes	Twitter handle without @, 1–100 characters (e.g. elonmusk)

Example

curl -G "https://api.pullbay.com/twitter/handle/elonmusk" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "user",
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk",
      "url": "https://x.com/elonmusk",
      "twitterUrl": "https://twitter.com/elonmusk",
      "description": "https://t.co/dDtDyVssfm",
      "location": "",
      "profilePicture": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_normal.jpg",
      "coverPicture": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
      "isVerified": true,
      "isBlueVerified": true,
      "protected": false,
      "canDm": false,
      "canMediaTag": false,
      "followers": 239698341,
      "following": 1319,
      "fastFollowersCount": 0,
      "favouritesCount": 225074,
      "listedCount": 168631,
      "mediaCount": 4467,
      "statusesCount": 101980,
      "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
      "status": ""
    }
  ],
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged.

---

Get User About By Handle

Returns extended profile / about details for a Twitter user, by handle.

Request

GET /twitter/handle/{handle}/about
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
handle	string	Yes	Twitter handle without @, 1–100 characters (e.g. elonmusk)

Example

curl -G "https://api.pullbay.com/twitter/handle/elonmusk/about" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "accountBasedIn": "United States",
      "locationAccurate": true,
      "profileImageShape": "Circle",
      "avatarUrl": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_normal.jpg",
      "usernameChangeCount": "0",
      "accountCreatedAt": "Tue Jun 02 20:12:29 +0000 2009",
      "accountSource": "United States App Store",
      "verifiedSince": "-156836000000000"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged.

---

Get User By ID

Returns a Twitter user by their numeric user ID.

Request

GET /twitter/user/{id}
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
id	string	Yes	Numeric Twitter user ID, 1–100 characters (e.g. 44196397)

Example

curl -G "https://api.pullbay.com/twitter/user/44196397" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "user",
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk",
      "url": "https://x.com/elonmusk",
      "twitterUrl": "https://twitter.com/elonmusk",
      "description": "https://t.co/dDtDyVssfm",
      "location": "",
      "profilePicture": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_normal.jpg",
      "coverPicture": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
      "isVerified": true,
      "isBlueVerified": true,
      "protected": false,
      "canDm": false,
      "canMediaTag": false,
      "followers": 239698341,
      "following": 1319,
      "fastFollowersCount": 0,
      "favouritesCount": 225074,
      "listedCount": 168631,
      "mediaCount": 4467,
      "statusesCount": 101980,
      "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
      "status": ""
    }
  ],
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged.

---

Get User's Tweets

Returns tweets posted by a user, by user ID.

Request

GET /twitter/user/{id}/tweets
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
id	string	Yes	Numeric Twitter user ID, 1–100 characters (e.g. 44196397)
cursor	string	No	Pagination cursor from a previous response. Mutually exclusive with maxItems
maxItems	integer	No	One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

Example

curl -G "https://api.pullbay.com/twitter/user/44196397/tweets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d maxItems=20

Response

{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "tweet",
      "id": "20",
      "url": "https://x.com/jack/status/20",
      "twitterUrl": "https://twitter.com/jack/status/20",
      "text": "just setting up my twttr",
      "fullText": "just setting up my twttr",
      "source": "Twitter Web Client",
      "lang": "en",
      "createdAt": "Tue Mar 21 20:50:14 +0000 2006",
      "conversationId": "20",
      "retweetCount": 126541,
      "replyCount": 17858,
      "likeCount": 309719,
      "quoteCount": 6384,
      "bookmarkCount": 21386,
      "viewCount": null,
      "isReply": false,
      "isPinned": false,
      "isRetweet": false,
      "isQuote": false,
      "author": {
        "type": "user",
        "id": "44196397",
        "userName": "elonmusk",
        "name": "Elon Musk",
        "url": "https://x.com/elonmusk",
        "twitterUrl": "https://twitter.com/elonmusk",
        "description": "https://t.co/dDtDyVssfm",
        "location": "",
        "profilePicture": "https://pbs.twimg.com/profile_images/2035314704307081216/71U1ftM3_normal.jpg",
        "coverPicture": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
        "isVerified": true,
        "isBlueVerified": true,
        "protected": false,
        "canDm": false,
        "canMediaTag": false,
        "followers": 239698341,
        "following": 1319,
        "fastFollowersCount": 0,
        "favouritesCount": 225074,
        "listedCount": 168631,
        "mediaCount": 4467,
        "statusesCount": 101980,
        "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
        "status": ""
      },
      "media": []
    }
  ],
  "pagination": { "page": null, "hasNextPage": true, "cursor": "DAACCgACGY...", "offset": null },
  "pricing": { "creditsCharged": 1 }
}

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of tweets returned, not the number of requests.

---

Object schemas

User object

Field	Type	Description
type	string	Always user
id	string	Numeric Twitter user ID
userName	string	Handle, without @
name	string	Display name
url / twitterUrl	string	Profile URL on x.com and twitter.com
description	string	Bio text
location	string	Free-text profile location
profilePicture / coverPicture	string	Avatar and banner image URLs
isVerified / isBlueVerified	boolean	Legacy verification and Blue subscriber verification
protected	boolean	Whether the account's tweets are protected
canDm / canMediaTag	boolean	Whether the user accepts DMs / can be tagged in media
followers / following	integer	Follower and following counts
fastFollowersCount	integer	Recently-gained follower count
favouritesCount	integer	Total likes given by the user
listedCount	integer	Number of lists the user appears on
mediaCount	integer	Number of tweets containing media
statusesCount	integer	Total tweet count
createdAt	string	Account creation timestamp (Twitter date format)
status	string	Reserved/internal status field

Tweet object

Field	Type	Description
type	string	Always tweet
id	string	Numeric tweet ID
url / twitterUrl	string	Tweet permalink on x.com and twitter.com
text / fullText	string	Tweet body (truncated and full)
source	string	Client used to post the tweet
lang	string	Tweet language code
createdAt	string	Posted timestamp (Twitter date format)
conversationId	string	ID of the root tweet in the thread
retweetCount / replyCount / likeCount / quoteCount / bookmarkCount	integer	Engagement counts
viewCount	integer, nullable	View count, when available
isReply / isPinned / isRetweet / isQuote	boolean	Tweet type flags
author	User object	The tweet's author
media	array	Attached media objects

User about object

Field	Type	Description
accountBasedIn	string	Inferred account region
locationAccurate	boolean	Whether accountBasedIn is considered accurate
profileImageShape	string	Profile picture mask shape (e.g. Circle)
avatarUrl	string	Avatar image URL
usernameChangeCount	string	Number of times the handle has been changed
accountCreatedAt	string	Account creation timestamp (Twitter date format)
accountSource	string	Platform/channel the account was created from
verifiedSince	string	Verification timestamp, when applicable

---

Errors

All non-2xx responses share the same envelope:

{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}

Status	Meaning
400	Bad request — missing/invalid parameters
402	Insufficient credits
404	Tweet or user not found

Looking Up Users: Handle vs. ID

Twitter users can be resolved two ways, and the right one depends on what you already have:

• By handle (/twitter/handle/{handle}, /twitter/handle/{handle}/about) — use when you have the @username (without the @). This is the natural entry point when a human gives you a Twitter handle.

• By numeric ID (/twitter/user/{id}, /twitter/user/{id}/tweets) — use when you already have the user's numeric ID, typically because you pulled it from author.id on a tweet or from a prior handle lookup's id field. Numeric IDs are stable even if a user changes their handle, so prefer caching the ID for repeated lookups.

This mirrors the Instagram service's handle-vs-ID split: resolve once by handle to get the numeric ID, then use the ID for subsequent lookups (like fetching a user's tweets) to avoid re-resolving the handle each time.

Profile detail also comes in two levels:

• Basic profile (/twitter/handle/{handle}, /twitter/user/{id}) — followers, bio, verification status, and engagement counters. Use this for most lookups.

• About / extended profile (/twitter/handle/{handle}/about) — additional metadata not on the basic profile, such as inferred account region, profile image shape, username change count, and verification timestamp. Only available via handle, not by numeric ID. Call this in addition to the basic profile when you need these extra fields.