Twitter batch user timeline API & latest tweets

{
  "tweets": [
    {
      "id": "1234567890",
      "text": "Just launched our new feature!",
      "createdAt": "2025-01-15T12:00:00Z",
      "likeCount": 42,
      "retweetCount": 5
    }
  ],
  "has_next_page": false,
  "next_cursor": "",
  "unavailable_ids": [
    "1234567890"
  ],
  "unprocessed_ids": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

users

batch

tweets

Twitter batch user timeline API & latest tweets

curl --request GET \
  --url https://xquik.com/api/v1/x/users/batch/tweets

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/batch/tweets"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "tweets": [
    {
      "id": "<string>",
      "text": "<string>",
      "type": "<string>",
      "createdAt": "<string>",
      "isNoteTweet": true,
      "isPinned": true,
      "likeCount": 123,
      "retweetCount": 123,
      "replyCount": 123,
      "quoteCount": 123,
      "viewCount": 123,
      "bookmarkCount": 123,
      "url": "<string>",
      "lang": "<string>",
      "isReply": true,
      "conversationId": "<string>",
      "isQuoteStatus": true,
      "isRetweet": true,
      "entities": {},
      "author": {},
      "media": [
        {}
      ],
      "quoted_tweet": {},
      "retweeted_tweet": {}
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>",
  "unavailable_ids": [
    "<string>"
  ],
  "unprocessed_ids": [
    "<string>"
  ]
}

Repost records include retweetedAt, the repost event’s UTC ISO 8601 timestamp. It is null when that timestamp is unavailable. The API omits it for original posts. The nested original post keeps its own creation date. This field does not report every account that reposted a post. Request per-account timestamps with Get retweeters.

When to use the batch timeline

Use this route to read the newest tweets of up to 20 users at once. It charges only for returned tweets. Use Get user timeline to page through 1 user’s older tweets.

Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.

1 credit per tweet returned · Accepts account credits and guest paid_reads

curl "https://xquik.com/api/v1/x/users/batch/tweets?usernames=nasa,openai&pageSize=5" \
  -H "x-api-key: xq_your_api_key_here" | jq

const usernames = ["nasa", "openai"];
const params = new URLSearchParams({ usernames: usernames.join(","), pageSize: "5" });
const response = await fetch(`https://xquik.com/api/v1/x/users/batch/tweets?${params}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));

const tweetRows = data.tweets.map((tweet) => ({
  tweet_id: tweet.id,
  text: tweet.text,
  author_id: tweet.author?.id ?? null,
  author_username: tweet.author?.username ?? null,
  created_at: tweet.createdAt ?? null,
  like_count: tweet.likeCount ?? null,
  is_pinned: tweet.isPinned ?? false,
}));
const sendAgain = data.unprocessed_ids;
const skip = data.unavailable_ids;

import requests

usernames = ["nasa", "openai"]
response = requests.get(
    "https://xquik.com/api/v1/x/users/batch/tweets",
    params={"usernames": ",".join(usernames), "pageSize": 5},
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
if not response.ok:
    raise RuntimeError(data)

tweet_rows = [
    {
        "tweet_id": tweet["id"],
        "text": tweet["text"],
        "author_id": (tweet.get("author") or {}).get("id"),
        "author_username": (tweet.get("author") or {}).get("username"),
        "created_at": tweet.get("createdAt"),
        "like_count": tweet.get("likeCount"),
        "is_pinned": tweet.get("isPinned", False),
    }
    for tweet in data["tweets"]
]
send_again = data["unprocessed_ids"]
skip = data["unavailable_ids"]

The Node.js and Python snippets build tweet rows. They do not print full response pages. Send unprocessed_ids again. Skip unavailable_ids.

Several timelines in 1 call

Tweets arrive user by user, in the order you named the users. Each user’s tweets are newest first, after the pinned tweet. Group rows by author.id. A call returns up to 20 tweets per user. Set pageSize to return fewer. A batch returns 1 page: has_next_page is false & next_cursor is empty.

Result	Where it appears	What to do
Tweets were read	`tweets`	Store the rows. Each costs 1 credit.
No account on X	`unavailable_ids`	Skip the user. It costs nothing.
Protected tweets	`unavailable_ids`	Skip the user. It costs nothing.
The read failed	`unprocessed_ids`	Send the user again. It costs nothing.
The call ran out of time	`unprocessed_ids`	Send the user again. It costs nothing.
Credits ran out	`unprocessed_ids`	Add credits, then send the user again.

A user with no tweets appears in neither list & adds no rows.

Query parameters

string

Comma-separated numeric user IDs. Maximum 20 per request. Send ids or usernames, not both. A user named twice is read once.

string

Comma-separated X usernames, with or without @, or profile links such as x.com/nasa, in place of ids. Maximum 20 per request. A name in another case is the same account.

integer

Tweets per user. Range: 1-20. Defaults to 20. Also read as limit, count, max_results, maxItems, max_items or per_page.

Headers

string

Full account API key. Session cookie and OAuth authentication are also supported.

string

Send Bearer xq_your_guest_key_here for an active paid_reads guest key.

Response

200 OK

object[]

Each user’s newest tweets, in the order the users were named. Tweet object fields.

string

Tweet ID.

string

Tweet text.

string

Tweet type. Omitted if unavailable.

string

ISO 8601 creation timestamp.

boolean

Whether this is a Note Tweet. Omitted if unavailable.

boolean

Whether the author pinned this post to their profile. Omitted if unavailable.

number

Like count. Omitted if unavailable.

number

Retweet count. Omitted if unavailable.

number

Reply count. Omitted if unavailable.

number

Quote tweet count. Omitted if unavailable.

number

View count. Omitted if unavailable.

number

Bookmark count. Omitted if unavailable.

string

Permalink URL on X. Omitted if unavailable.

string

Tweet language code. Omitted if unavailable.

boolean

Whether the tweet is a reply. Omitted if unavailable.

string

Conversation thread ID. Omitted if unavailable.

boolean

Whether this tweet quotes another tweet. Omitted if unavailable.

boolean

Whether this row is a retweet. text carries the original post in full.

object

Parsed entities. Omitted if unavailable.

object

Tweet author profile. Omitted if unavailable. Author object fields.

string

Author user ID.

string

Author handle without @.

string

Author display name. Omitted if unavailable.

number

Follower count. Omitted if unavailable.

boolean

Whether the author is verified. Omitted if unavailable.

string

Author profile image URL. Omitted if unavailable.

object[]

Media attachments. Omitted when the tweet has no media. Media object fields.

string

Direct media URL.

object[]

Available video renditions with bitrate, content type, and URL. Omitted for images.

string

Media type.

string

Shortened URL from the tweet text.

object

Embedded quoted tweet. Omitted if not a quote tweet.

object

Original retweeted tweet. Omitted if not a retweet.

boolean

Always false for batch requests.

string

Always empty for batch requests.

string[]

Users with no account on X or with protected tweets. They cost nothing. Skip them.

string[]

Users the call did not read. They cost nothing. Send them again.

Both lists name each user as you sent it: an ID, or a username. A profile link is named by its username.

{
  "tweets": [
    {
      "id": "1893456789012345678",
      "text": "Hello world!",
      "createdAt": "2026-03-27T10:00:00.000Z",
      "likeCount": 42,
      "retweetCount": 5,
      "author": {
        "id": "9876543210",
        "username": "username",
        "name": "Xquik",
        "followers": 12000,
        "verified": true,
        "profilePicture": "https://pbs.twimg.com/profile_images/example.jpg"
      }
    }
  ],
  "has_next_page": false,
  "next_cursor": "",
  "unavailable_ids": ["1234567890"],
  "unprocessed_ids": []
}

400 Missing IDs

{ "error": "missing_ids", "message": "ids parameter required" }

Send ids or usernames.

400 Too many IDs

{ "error": "too_many_ids", "message": "Max 20 IDs per request" }

400 Invalid user IDs

{
  "error": "invalid_user_ids",
  "message": "usernames must contain 1-20 X usernames or profile links such as x.com/nasa."
}

Each ids value must be a numeric user ID. Each usernames value must be a username or a link to a profile on x.com or twitter.com. Sending both ids & usernames also answers 400. The request costs nothing.

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

{ "error": "unauthenticated" }

402 Payment required

Full account keys can receive no_subscription, subscription_inactive, no_credits, or insufficient_credits with account payment options. Guest keys receive only the guest top-up action. The failed request creates no checkout. Ask the user to confirm before calling any checkout or top-up route.

502 X API unavailable

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

503 No user could be read

{ "error": "x_api_unavailable" }

No user’s tweets could be read. The request costs nothing. Wait for the Retry-After header, then send it again.

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Dependency failed

{ "error": "x_api_unavailable" }

The normalized v1 response contract can return 424 when the read service is unavailable.

Related. Get user timeline · Batch Users · Batch Tweets

{
  "tweets": [
    {
      "id": "1234567890",
      "text": "Just launched our new feature!",
      "createdAt": "2025-01-15T12:00:00Z",
      "likeCount": 42,
      "retweetCount": 5
    }
  ],
  "has_next_page": false,
  "next_cursor": "",
  "unavailable_ids": [
    "1234567890"
  ],
  "unprocessed_ids": []
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter batch user timeline API & latest tweets

curl --request GET \
  --url https://xquik.com/api/v1/x/users/batch/tweets

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/batch/tweets"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "tweets": [
    {
      "id": "<string>",
      "text": "<string>",
      "type": "<string>",
      "createdAt": "<string>",
      "isNoteTweet": true,
      "isPinned": true,
      "likeCount": 123,
      "retweetCount": 123,
      "replyCount": 123,
      "quoteCount": 123,
      "viewCount": 123,
      "bookmarkCount": 123,
      "url": "<string>",
      "lang": "<string>",
      "isReply": true,
      "conversationId": "<string>",
      "isQuoteStatus": true,
      "isRetweet": true,
      "entities": {},
      "author": {},
      "media": [
        {}
      ],
      "quoted_tweet": {},
      "retweeted_tweet": {}
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>",
  "unavailable_ids": [
    "<string>"
  ],
  "unprocessed_ids": [
    "<string>"
  ]
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter batch user timeline API & latest tweets

When to use the batch timeline

Several timelines in 1 call

Query parameters

Headers

Response

200 OK

400 Missing IDs

400 Too many IDs

400 Invalid user IDs

401 Unauthenticated

402 Payment required

502 X API unavailable

503 No user could be read

429 Rate limit exceeded

424 Dependency failed

​When to use the batch timeline

​Several timelines in 1 call

​Query parameters

​Headers

​Response

​200 OK

​400 Missing IDs

​400 Too many IDs

​400 Invalid user IDs

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​503 No user could be read

​429 Rate limit exceeded

​424 Dependency failed

When to use the batch timeline

Several timelines in 1 call

Query parameters

Headers

Response

200 OK

400 Missing IDs

400 Too many IDs

400 Invalid user IDs

401 Unauthenticated

402 Payment required

502 X API unavailable

503 No user could be read

429 Rate limit exceeded

424 Dependency failed