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

x-api