Get User Timeline | API Docs

Query a user's timeline by normalized user ID. The endpoint returns X API v2-style data / includes / meta structures.

text

GET https://api.requestbeam.com/v1/twitter/users/{id}/tweets

Authentication

All Twitter API endpoints require Bearer Token authentication.

http

Authorization: Bearer YOUR_API_KEY

Path Parameters

idstringrequired

Twitter user ID, such as 44196397.

Query Parameters

max_resultsintegerDefault: 10

Number of tweets to return in one page, from 1 to 100.

pagination_tokenstring

Cursor for the next page, copied from the previous response's meta.next_token.

excludestring

Comma-separated exclusion policy. Supported values include replies and retweets.

expansionsstring

Comma-separated expansion fields. Use author_id to include includes.users.

tweet.fieldsstring

Comma-separated tweet fields, such as created_at,public_metrics,attachments,source.

user.fieldsstring

Controls fields in includes.users when expansions=author_id is requested.

Request Example

bash

curl --request GET \
  "$API_BASE_URL/v1/twitter/users/44196397/tweets?max_results=5&exclude=retweets,replies&expansions=author_id&tweet.fields=created_at,public_metrics,attachments,author_id,conversation_id&user.fields=public_metrics" \
  --header "Authorization: Bearer YOUR_API_KEY"

Response

dataobject[]required

Timeline tweet list.

Tweet fields

idstringrequired

Tweet ID.

textstringrequired

Tweet text content.

attachmentsobject

Media references, currently returned as media_keys.

author_idstring

Author ID. When expansions=author_id is requested, it corresponds to includes.users.

conversation_idstring

Conversation ID.

created_atstring

Tweet creation time in ISO 8601 format.

edit_history_tweet_idsstring[]

Tweet IDs in the edit history.

entitiesobject

Parsed tweet entities, such as hashtags, URLs, and mentions.

in_reply_to_user_idstring

ID of the user being replied to.

langstring

Tweet language.

possibly_sensitiveboolean

Whether the content is sensitive.

public_metricsobject

Public tweet metrics.

public_metrics fields

retweet_countinteger

Number of retweets.

reply_countinteger

Number of replies.

like_countinteger

Number of likes.

quote_countinteger

Number of quotes.

bookmark_countinteger

Number of bookmarks.

impression_countinteger

Number of impressions.

referenced_tweetsobject[]

Referenced tweets. type may be retweeted, quoted, or replied_to.

sourcestring

Tweet source, such as a client or the Web.

includesobject

Expanded objects. Appears when expansions includes author_id.

includes fields

usersobject[]

Author list corresponding to author_id.

metaobjectrequired

Pagination and result metadata.

meta fields

newest_idstring

Newest tweet ID in the current page.

oldest_idstring

Oldest tweet ID in the current page.

next_tokenstring

Cursor for the next page. Send it as pagination_token.

result_countintegerrequired

Number of tweets in the current page.

Success Example

json

{
  "data": [
    {
      "id": "tweet-1",
      "text": "Hello Mars",
      "author_id": "44196397",
      "created_at": "2025-04-22T10:00:00.000Z",
      "public_metrics": {
        "retweet_count": 3,
        "reply_count": 2,
        "like_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "44196397",
        "name": "Elon Musk",
        "username": "elonmusk"
      }
    ]
  },
  "meta": {
    "newest_id": "tweet-1",
    "oldest_id": "tweet-1",
    "next_token": "cursor-123",
    "result_count": 1
  }
}

Error Response

See Error Codes and Troubleshooting for the full code reference, protocol differences, and diagnostic steps.

json

{
  "success": false,
  "error": {
    "code": 40000,
    "message": "Insufficient credit. Required: 100000, Available: 99999"
  },
  "requestId": "req_xxx"
}

Pagination

If meta.next_token is present, pass it as pagination_token to fetch the next page.