Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Twitter / X

The Pullbay Twitter API provides programmatic access to public Twitter/X data — tweet search, individual tweets, and user profiles by handle or numeric ID. Integrate Twitter data into your applications, dashboards, and analytics pipelines without scraping or using the official Twitter/X developer platform.

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

Overview

The Twitter service lets you:

  • Search tweets by keyword, sorted by Top or Latest

  • Look up a single tweet by its numeric ID

  • Look up a user profile by handle (@username) or by numeric user ID

  • Fetch extended "about" details for a user (account region, profile image shape, username change history)

  • Pull all tweets posted by a given user

All endpoints are read-only GET requests against public Twitter/X data — no posting, no DMs, and no authenticated account access is included.

Common Use Cases

Brand & Keyword Monitoring — Search for mentions of a brand, product, or keyword and feed matching tweets into your own alerting or sentiment pipeline.

Influencer & Competitor Tracking — Pull a user's profile and recent tweets to track follower growth, posting cadence, and engagement trends over time.

Content Research — Use Search Twitter to discover what's being said about a topic, then pull the authoring accounts' profiles to understand who's driving the conversation.

Lead & Audience Enrichment — Resolve a handle to its numeric user ID and profile fields (bio, follower count, verification status) to enrich a CRM record or audience segment.

Historical Tweet Lookup — Fetch a specific tweet by ID when you already have a link or ID from another source and need the full text, engagement counts, and author details.

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

Parameters

Parameter
Type
Required
Default
Description

query

string

Yes

—

Search query, 1–100 characters

sort

string

No

Latest

Top or Latest

useFirst

string (true/false)

No

false

true or false

maxItems

integer

No

—

One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

cursor

string

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Tweet objects

pagination.page

null

Unused by this endpoint — always null here

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.offset

null

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate — read the figure from each response.

Get Tweet

Returns a single tweet by its numeric ID.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string

Yes

—

Numeric tweet ID, 1–100 characters (e.g. 20)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single Tweet object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get User By Handle

Returns a Twitter user by handle (without @).

Request

Parameters

Parameter
Type
Required
Default
Description

handle

string

Yes

—

Twitter handle without @, 1–100 characters (e.g. elonmusk)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User About By Handle

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

Request

Parameters

Parameter
Type
Required
Default
Description

handle

string

Yes

—

Twitter handle without @, 1–100 characters (e.g. elonmusk)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User About object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User By ID

Returns a Twitter user by their numeric user ID.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string

Yes

—

Numeric Twitter user ID, 1–100 characters (e.g. 44196397)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User's Tweets

Returns tweets posted by a user, by user ID.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string

Yes

—

Numeric Twitter user ID, 1–100 characters (e.g. 44196397)

maxItems

integer

No

—

One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

cursor

string

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Tweet objects

pagination.page

null

Unused by this endpoint — always null here

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.offset

null

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No flat per-request rate is published — read the figure from each response.

Errors

All non-2xx responses share the same envelope:

Status
Meaning

400

Bad request — missing/invalid parameters

402

Insufficient credits

404

Tweet or user not found

Object Schema

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 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

Note: User object is the schema returned by both Get User By Handle and Get User By ID — it is a distinct object from User About object below, which only the about/bio endpoint returns.

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 (returned as a string)

accountCreatedAt

string

Account creation timestamp (Twitter date format)

accountSource

string

Platform/channel the account was created from

verifiedSince

string

Verification timestamp, when applicable (returned as a string)

Note: the User About object does not include id, userName, or any other linking field back to the User object — correlate the two by the handle you requested, not by a shared key in the response body.

Finding User and Tweet IDs

  • Handle: the @username shown on a profile or in a tweet URL, without the @ (e.g. https://x.com/elonmusk → elonmusk). Pass this to the /twitter/handle/{handle} and /twitter/handle/{handle}/about endpoints.

  • Numeric user ID: a stable internal ID, distinct from the handle. You can get it from a prior handle lookup's id field, or from a tweet's author.id. Pass this to /twitter/user/{id} and /twitter/user/{id}/tweets. Numeric IDs don't change even if a user changes their handle, so prefer caching the ID for repeated lookups.

  • Tweet ID: the numeric ID in a tweet's URL, e.g. https://x.com/jack/status/20 → 20. Pass this to /twitter/tweet/{id}.

  • Handle and numeric ID resolve to the same user but are not interchangeable inputs — each endpoint accepts only one or the other, not both.

Python Example

This example fetches all tweets for a user a page at a time, following the cursor returned in pagination.cursor until pagination.hasNextPage is false or the page cap is reached:

Each request is billed independently, with the charged amount reported in that response's pricing.creditsCharged — there's no separate "fetch everything in one call" endpoint, so a multi-page pull like this makes one request per page.

FAQ

How do I find a user's numeric ID if I only have their handle?

Call /twitter/handle/{handle} first — the response's id field is the numeric user ID. You can also get a user's numeric ID from author.id on any of their tweets.

What's the difference between the basic user lookup and the "about" endpoint?

The basic lookup (/twitter/handle/{handle} or /twitter/user/{id}) returns the User object: bio, follower counts, verification status, and engagement counters. The about endpoint (/twitter/handle/{handle}/about) returns a separate User About object with different fields — inferred account region, profile image shape, username change count, and verification timestamp. The about endpoint is only available by handle, not by numeric ID.

Is useFirst a boolean?

No. It's documented and validated as a string with the literal enum values true and false, not a JSON boolean. Send it as the string "true" or "false" (e.g. useFirst=true in a query string), not as a boolean literal.

How many tweets can I fetch in one call?

Up to 200 with maxItems on Search Twitter or Get User's Tweets. cursor and maxItems are mutually exclusive — use one or the other per request.

Can I sort search results?

Yes — sort accepts Top or Latest (default Latest). There's no other sort order published for search.

What's the credit cost per request?

It's dynamic — every response includes pricing.creditsCharged with the exact amount for that call. There's no fixed published rate per endpoint or per result.

PreviousTikTok
NextErrors and Retries

Last updated