> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/twitter.md).

# Twitter

Twitter: tweets, users, handles, and search.

## Search Twitter

> Search tweets by query. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive). \`sort\` is \`Top\` or \`Latest\` (default \`Latest\`).\
> \
> \*\*Cost: 160 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterTweet":{"type":"object","description":"A single tweet.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"text":{"type":"string"},"fullText":{"type":"string"},"source":{"type":"string"},"lang":{"type":"string"},"createdAt":{"type":"string"},"conversationId":{"type":"string"},"retweetCount":{"type":"integer"},"replyCount":{"type":"integer"},"likeCount":{"type":"integer"},"quoteCount":{"type":"integer"},"bookmarkCount":{"type":"integer"},"viewCount":{"type":"integer","nullable":true},"isReply":{"type":"boolean"},"isPinned":{"type":"boolean"},"isRetweet":{"type":"boolean"},"isQuote":{"type":"boolean"},"author":{"$ref":"#/components/schemas/TwitterUser"},"media":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"TwitterUser":{"type":"object","description":"A Twitter user profile.","properties":{"type":{"type":"string"},"id":{"type":"string"},"userName":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"profilePicture":{"type":"string"},"coverPicture":{"type":"string"},"isVerified":{"type":"boolean"},"isBlueVerified":{"type":"boolean","nullable":true},"protected":{"type":"boolean"},"canDm":{"type":"boolean"},"canMediaTag":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"fastFollowersCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"listedCount":{"type":"integer"},"mediaCount":{"type":"integer"},"statusesCount":{"type":"integer"},"createdAt":{"type":"string"},"status":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/search":{"get":{"operationId":"searchTwitter","summary":"Search Twitter","description":"Search tweets by query. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive). `sort` is `Top` or `Latest` (default `Latest`).\n\n**Cost: 160 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"sort","in":"query","required":false,"schema":{"default":"Latest","type":"string","enum":["Top","Latest"]}},{"name":"useFirst","in":"query","required":false,"schema":{"default":"false","type":"string","enum":["true","false"]}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterTweet"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get a tweet by ID

> Returns a single tweet by its numeric ID.\
> \
> \*\*Cost: 4 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterTweet":{"type":"object","description":"A single tweet.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"text":{"type":"string"},"fullText":{"type":"string"},"source":{"type":"string"},"lang":{"type":"string"},"createdAt":{"type":"string"},"conversationId":{"type":"string"},"retweetCount":{"type":"integer"},"replyCount":{"type":"integer"},"likeCount":{"type":"integer"},"quoteCount":{"type":"integer"},"bookmarkCount":{"type":"integer"},"viewCount":{"type":"integer","nullable":true},"isReply":{"type":"boolean"},"isPinned":{"type":"boolean"},"isRetweet":{"type":"boolean"},"isQuote":{"type":"boolean"},"author":{"$ref":"#/components/schemas/TwitterUser"},"media":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"TwitterUser":{"type":"object","description":"A Twitter user profile.","properties":{"type":{"type":"string"},"id":{"type":"string"},"userName":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"profilePicture":{"type":"string"},"coverPicture":{"type":"string"},"isVerified":{"type":"boolean"},"isBlueVerified":{"type":"boolean","nullable":true},"protected":{"type":"boolean"},"canDm":{"type":"boolean"},"canMediaTag":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"fastFollowersCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"listedCount":{"type":"integer"},"mediaCount":{"type":"integer"},"statusesCount":{"type":"integer"},"createdAt":{"type":"string"},"status":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/tweet/{id}":{"get":{"operationId":"getTwitterTweet","summary":"Get a tweet by ID","description":"Returns a single tweet by its numeric ID.\n\n**Cost: 4 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterTweet"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get a user by handle

> Returns a Twitter user by handle (without \`@\`).\
> \
> \*\*Cost: 40 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterUser":{"type":"object","description":"A Twitter user profile.","properties":{"type":{"type":"string"},"id":{"type":"string"},"userName":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"profilePicture":{"type":"string"},"coverPicture":{"type":"string"},"isVerified":{"type":"boolean"},"isBlueVerified":{"type":"boolean","nullable":true},"protected":{"type":"boolean"},"canDm":{"type":"boolean"},"canMediaTag":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"fastFollowersCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"listedCount":{"type":"integer"},"mediaCount":{"type":"integer"},"statusesCount":{"type":"integer"},"createdAt":{"type":"string"},"status":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/handle/{handle}":{"get":{"operationId":"getTwitterUserByHandle","summary":"Get a user by handle","description":"Returns a Twitter user by handle (without `@`).\n\n**Cost: 40 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterUser"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get a user about by handle

> Returns the about/bio details for a Twitter user by handle.\
> \
> \*\*Cost: 2 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterUserAbout":{"type":"object","description":"Extended profile / about details for a Twitter user.","properties":{"accountBasedIn":{"type":"string"},"locationAccurate":{"type":"boolean"},"profileImageShape":{"type":"string"},"avatarUrl":{"type":"string"},"usernameChangeCount":{"type":"string"},"accountCreatedAt":{"type":"string"},"accountSource":{"type":"string"},"verifiedSince":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/handle/{handle}/about":{"get":{"operationId":"getTwitterUserAbout","summary":"Get a user about by handle","description":"Returns the about/bio details for a Twitter user by handle.\n\n**Cost: 2 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterUserAbout"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get a user by ID

> Returns a Twitter user by their numeric user ID.\
> \
> \*\*Cost: 40 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterUser":{"type":"object","description":"A Twitter user profile.","properties":{"type":{"type":"string"},"id":{"type":"string"},"userName":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"profilePicture":{"type":"string"},"coverPicture":{"type":"string"},"isVerified":{"type":"boolean"},"isBlueVerified":{"type":"boolean","nullable":true},"protected":{"type":"boolean"},"canDm":{"type":"boolean"},"canMediaTag":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"fastFollowersCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"listedCount":{"type":"integer"},"mediaCount":{"type":"integer"},"statusesCount":{"type":"integer"},"createdAt":{"type":"string"},"status":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/user/{id}":{"get":{"operationId":"getTwitterUserById","summary":"Get a user by ID","description":"Returns a Twitter user by their numeric user ID.\n\n**Cost: 40 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterUser"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get tweets posted by a user

> Returns tweets posted by a user, by user ID. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 160 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"twitter","description":"Twitter: tweets, users, handles, and search."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TwitterTweet":{"type":"object","description":"A single tweet.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"text":{"type":"string"},"fullText":{"type":"string"},"source":{"type":"string"},"lang":{"type":"string"},"createdAt":{"type":"string"},"conversationId":{"type":"string"},"retweetCount":{"type":"integer"},"replyCount":{"type":"integer"},"likeCount":{"type":"integer"},"quoteCount":{"type":"integer"},"bookmarkCount":{"type":"integer"},"viewCount":{"type":"integer","nullable":true},"isReply":{"type":"boolean"},"isPinned":{"type":"boolean"},"isRetweet":{"type":"boolean"},"isQuote":{"type":"boolean"},"author":{"$ref":"#/components/schemas/TwitterUser"},"media":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"TwitterUser":{"type":"object","description":"A Twitter user profile.","properties":{"type":{"type":"string"},"id":{"type":"string"},"userName":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"twitterUrl":{"type":"string"},"description":{"type":"string"},"location":{"type":"string"},"profilePicture":{"type":"string"},"coverPicture":{"type":"string"},"isVerified":{"type":"boolean"},"isBlueVerified":{"type":"boolean","nullable":true},"protected":{"type":"boolean"},"canDm":{"type":"boolean"},"canMediaTag":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"fastFollowersCount":{"type":"integer"},"favouritesCount":{"type":"integer"},"listedCount":{"type":"integer"},"mediaCount":{"type":"integer"},"statusesCount":{"type":"integer"},"createdAt":{"type":"string"},"status":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/twitter/user/{id}/tweets":{"get":{"operationId":"getTwitterUserTweets","summary":"Get tweets posted by a user","description":"Returns tweets posted by a user, by user ID. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 160 credits/request + 1 credit/item**","tags":["twitter"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/TwitterTweet"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```