X API: Query the X (Twitter) API v2 with curl

Overview

Use curl commands to interact with the X (Twitter) API v2. This skill covers read-only, public endpoints that do not require an authenticated user context — things like looking up profiles, searching recent posts, and retrieving tweets.

Authentication assumption: The environment variable X_BEARER_TOKEN must already be set with a valid X API v2 Bearer Token. All commands below rely on it.

How to use

All requests follow this pattern:

curl "<endpoint_url>"
-H "Authorization: Bearer $X_BEARER_TOKEN"

For any endpoint that returns tweets, always include note_tweet in tweet.fields so long posts return full content.

Required response-handling workflow

Always write API responses to a file first, then read/search only the fields you need. Do not paste large raw JSON directly into chat output.

1) Store response

curl -sS "<endpoint_url>"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_api_response.json

2) Inspect or extract specific fields

jq '.' /tmp/x_api_response.json jq '.data' /tmp/x_api_response.json jq -r '.data[]?.text' /tmp/x_api_response.json rg -n "next_token|id|username" /tmp/x_api_response.json

If the response is large, summarize using targeted jq queries (counts, IDs, timestamps, specific text fields) instead of returning entire payloads.

Examples

Get a user profile

curl -sS "https://api.x.com/2/users/by/username/xdevelopers"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_user_profile.json jq '.data' /tmp/x_user_profile.json

Get a user profile with additional fields

curl -sS "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_user_profile_fields.json jq '.data | {id,username,created_at,description,public_metrics}' /tmp/x_user_profile_fields.json

Common user.fields : created_at , description , entities , id , location , name , pinned_tweet_id , profile_image_url , protected , public_metrics , url , username , verified , withheld .

Look up a post by ID

curl -sS "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=note_tweet,created_at,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_tweet_lookup.json jq '.data | {id,created_at,text,note_tweet,public_metrics}' /tmp/x_tweet_lookup.json

Common tweet.fields : note_tweet , attachments , author_id , conversation_id , created_at , entities , id , in_reply_to_user_id , lang , public_metrics , referenced_tweets , source , text , withheld .

Search recent posts

curl -sS "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&#x26;tweet.fields=note_tweet,created_at"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_recent_search.json jq -r '.data[]? | [.id, .created_at, (.note_tweet.text // .text)] | @tsv' /tmp/x_recent_search.json

The query parameter supports the full X search query syntax. Examples:

• from:username — posts from a specific user

• to:username — replies to a specific user

• "exact phrase" — posts containing an exact phrase

• keyword1 keyword2 — posts containing both keywords

• keyword1 OR keyword2 — posts containing either keyword

• #hashtag — posts with a specific hashtag

• has:media — posts that contain media

• has:links — posts that contain links

• lang:en — posts in a specific language

Get a user's posts

curl -sS "https://api.x.com/2/users/2244994945/tweets?max_results=5&#x26;tweet.fields=note_tweet"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_user_tweets.json jq -r '.data[]? | [.id, (.note_tweet.text // .text)] | @tsv' /tmp/x_user_tweets.json

You can add more tweet.fields , max_results (5-100), and pagination tokens to customize the response, but always keep note_tweet included.

Get a user's mentions

curl -sS "https://api.x.com/2/users/2244994945/mentions?max_results=5&#x26;tweet.fields=note_tweet,created_at,author_id"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_user_mentions.json jq -r '.data[]? | [.id, .author_id, .created_at, (.note_tweet.text // .text)] | @tsv' /tmp/x_user_mentions.json

Look up multiple users by username

curl -sS "https://api.x.com/2/users/by?usernames=xdevelopers,twitterdev&#x26;user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_users_by_username.json jq '.data[] | {id,username,description,public_metrics}' /tmp/x_users_by_username.json

Get tweet counts for a search query

curl -sS "https://api.x.com/2/tweets/counts/recent?query=from:xdevelopers"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_tweet_counts.json jq '.meta, .data[:5]' /tmp/x_tweet_counts.json

Returns the count of tweets matching the query, grouped by time period.

Get a user's followers

curl -sS "https://api.x.com/2/users/2244994945/followers?max_results=10&#x26;user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_followers.json jq '.data[] | {id,username,public_metrics}' /tmp/x_followers.json

Get accounts a user is following

curl -sS "https://api.x.com/2/users/2244994945/following?max_results=10&#x26;user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_following.json jq '.data[] | {id,username,public_metrics}' /tmp/x_following.json

Look up a list and its members

Get list details

curl -sS "https://api.x.com/2/lists/84839422"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_list_details.json jq '.data' /tmp/x_list_details.json

Get list members

curl -sS "https://api.x.com/2/lists/84839422/members?user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"
-o /tmp/x_list_members.json jq '.data[] | {id,username,public_metrics}' /tmp/x_list_members.json

Tips

• To find a user's numeric ID (needed for some endpoints), first look them up by username, then use the id field from the response.

• Use expansions to include related objects in the response. For example, expansions=author_id on a tweet lookup will include the author's user object.

• Pagination: When results span multiple pages, the response includes a next_token field. Pass it as pagination_token in the next request.

• Rate limits vary by endpoint. If you receive a 429 response, wait before retrying.

• Prefer curl -sS -o <file> with follow-up jq filters so output remains compact and targeted.

API Reference

Full OpenAPI specification: https://api.x.com/2/openapi.json

Authentication

The X_BEARER_TOKEN environment variable must be set with a valid Bearer Token. This token provides app-only authentication, which grants access to public read-only endpoints.

To obtain a Bearer Token, create a project and app in the X Developer Portal and generate a Bearer Token from your app's "Keys and tokens" settings.