X (Twitter) API

Use the X API v2 via direct curl calls to read tweets, search posts, view user profiles, timelines, and social graphs.

Official docs: https://docs.x.com/x-api

When to Use

Use this skill when you need to:

View user profiles - look up users by username or ID
Read tweets - get tweet details by ID
Browse timelines - get a user's tweets or mentions
Search posts - find recent tweets matching a query
Explore social graphs - list followers and following

Prerequisites

Go to vm0.ai Settings → Connectors and connect X (Twitter). vm0 will automatically inject the required X_ACCESS_TOKEN environment variable.

Verify authentication:

bash -c 'curl -s "https://api.x.com/2/users/me" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .

Available Scopes

The connector grants read-only access:

tweet.read - Read tweets and timelines
users.read - Read user profiles
follows.read - Read followers and following

Important: When using $X_ACCESS_TOKEN in a command that pipes to another command, wrap the curl in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

How to Use

Base URL: https://api.x.com/2

1. Get Authenticated User Profile

Get the profile of the currently authenticated user:

bash -c 'curl -s "https://api.x.com/2/users/me?user.fields=id,name,username,description,profile_image_url,public_metrics,created_at,verified" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .data

2. Look Up User by Username

Get a user's profile by their username:

Note: Replace elonmusk with the actual username you want to look up.

USERNAME="elonmusk"

bash -c 'curl -s "https://api.x.com/2/users/by/username/$USERNAME?user.fields=id,name,username,description,public_metrics,created_at,verified,profile_image_url" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .data

3. Look Up User by ID

Get a user's profile by their user ID:

Note: Replace 12345 with the actual user ID. You can obtain user IDs from other endpoint responses.

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID?user.fields=id,name,username,description,public_metrics,created_at" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .data

4. Look Up Multiple Users

Get profiles for multiple users at once (up to 100):

Note: Replace the IDs with actual user IDs, comma-separated.

bash -c 'curl -s "https://api.x.com/2/users?ids=12345,67890&user.fields=id,name,username,description,public_metrics" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .data

5. Get a Tweet by ID

Get details of a specific tweet:

Note: Replace 1234567890 with the actual tweet ID.

TWEET_ID="1234567890"

bash -c 'curl -s "https://api.x.com/2/tweets/$TWEET_ID?tweet.fields=created_at,public_metrics,author_id,conversation_id,lang&expansions=author_id&user.fields=name,username" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .

6. Get Multiple Tweets

Get details for multiple tweets at once (up to 100):

Note: Replace the IDs with actual tweet IDs, comma-separated.

bash -c 'curl -s "https://api.x.com/2/tweets?ids=1234567890,0987654321&tweet.fields=created_at,public_metrics,author_id,text&expansions=author_id&user.fields=name,username" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .

7. Get User's Tweets (Timeline)

Get recent tweets posted by a user:

Note: Replace USER_ID with the actual user ID. Use the "Look Up User by Username" endpoint first to get the ID.

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID/tweets?max_results=10&tweet.fields=created_at,public_metrics,text&expansions=referenced_tweets.id" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, text: .text[0:120], created_at, public_metrics}'

Query parameters:

max_results - 5 to 100 (default: 10)
start_time / end_time - ISO 8601 datetime filter
since_id / until_id - Tweet ID boundaries
pagination_token - For paginating results
exclude - Comma-separated: retweets, replies

8. Get User's Mentions

Get recent tweets that mention a user:

Note: Replace USER_ID with the actual user ID.

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID/mentions?max_results=10&tweet.fields=created_at,public_metrics,author_id,text&expansions=author_id&user.fields=name,username" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, text: .text[0:120], author: .author_id, created_at}'

9. Get Reverse Chronological Timeline

Get the authenticated user's home timeline (tweets from people they follow):

Note: Replace USER_ID with the authenticated user's ID (from "Get Authenticated User Profile").

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID/timelines/reverse_chronological?max_results=10&tweet.fields=created_at,public_metrics,author_id,text&expansions=author_id&user.fields=name,username" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, text: .text[0:120], created_at}'

10. Search Recent Tweets

Search for tweets from the past 7 days:

Note: Replace the query with your search terms. The query supports operators like from:, to:, has:, -is:retweet, etc.

bash -c 'curl -s -G "https://api.x.com/2/tweets/search/recent" --data-urlencode "query=openai lang:en -is:retweet" --data-urlencode "max_results=10" --data-urlencode "tweet.fields=created_at,public_metrics,author_id,text" --data-urlencode "expansions=author_id" --data-urlencode "user.fields=name,username" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, text: .text[0:120], created_at, public_metrics}'

Common search operators:

from:username - Tweets from a specific user
to:username - Tweets replying to a user
@username - Tweets mentioning a user
#hashtag - Tweets with a hashtag
has:links / has:images / has:videos - Media filters
-is:retweet - Exclude retweets
-is:reply - Exclude replies
lang:en - Filter by language
conversation_id:123 - Tweets in a conversation thread

11. Get User's Followers

Get a list of users who follow a specific user:

Note: Replace USER_ID with the actual user ID.

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID/followers?max_results=20&user.fields=id,name,username,description,public_metrics" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, name, username, followers_count: .public_metrics.followers_count}'

12. Get User's Following

Get a list of users that a specific user follows:

Note: Replace USER_ID with the actual user ID.

USER_ID="12345"

bash -c 'curl -s "https://api.x.com/2/users/$USER_ID/following?max_results=20&user.fields=id,name,username,description,public_metrics" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq '.data[] | {id, name, username, followers_count: .public_metrics.followers_count}'

Pagination

Most list endpoints support pagination via pagination_token. Check the meta.next_token field in the response:

bash -c 'curl -s "https://api.x.com/2/tweets/search/recent?query=example&max_results=10" --header "Authorization: Bearer $X_ACCESS_TOKEN"' | jq .meta

Use the returned next_token value as pagination_token in the next request to get more results.

Common user.fields

Field	Description
`id`	Unique user ID
`name`	Display name
`username`	Handle (without @)
`description`	Bio text
`created_at`	Account creation date
`public_metrics`	Followers, following, tweet, and listed counts
`profile_image_url`	Avatar URL
`verified`	Verification status
`location`	User-defined location
`url`	User-defined URL

Common tweet.fields

Field	Description
`id`	Unique tweet ID
`text`	Tweet content
`created_at`	Post timestamp
`author_id`	Author's user ID
`public_metrics`	Retweets, replies, likes, quotes, bookmarks, impressions
`conversation_id`	Thread root tweet ID
`lang`	Detected language
`referenced_tweets`	Retweet/quote/reply references
`entities`	URLs, hashtags, mentions, cashtags

Guidelines

Read-only access: This connector only grants read permissions; you cannot post, like, or retweet
Rate limits: X API has strict rate limits; avoid rapid successive calls
User IDs vs usernames: Most endpoints require numeric user IDs, not usernames. Use the username lookup endpoint first
Fields are opt-in: The API only returns id and text by default; always specify tweet.fields and user.fields for richer data
7-day search window: The recent search endpoint only covers the past 7 days
Pagination: Use max_results and pagination_token for large result sets