Integration Guide

Key concepts and best practices for integrating Search Posts

This guide covers the key concepts you need to integrate the Search Posts endpoints into your application.

---

Authentication

Recent search

Recent search supports multiple authentication methods:

Method	Use case
OAuth 2.0 App-Only	Public Post data
OAuth 2.0 Authorization Code with PKCE	Private metrics
OAuth 1.0a User Context	Private metrics

Full-archive search

Full-archive search only supports OAuth 2.0 App-Only authentication.

Private metrics (non_public_metrics, organic_metrics, promoted_metrics) are not available with full-archive search because it only supports App-Only authentication.

---

Building queries

Queries use operators to match Posts. Combine operators with boolean logic:

(AI OR "machine learning") lang:en -is:retweet has:links

Query length limits

Access level	Recent search	Full-archive search
Self-serve	512 chars	1,024 chars
Enterprise	4,096 chars	4,096 chars

Operator types

Type	Description	Example
Standalone	Can be used alone	#python, from:user
Conjunction-required	Must be used with a standalone operator	has:media, is:retweet

Build a query

Learn query syntax in detail

Operator reference

See all available operators

---

Fields and expansions

By default, the response includes only id, text, and edit_history_tweet_ids. Use parameters to request additional data.

Example request

cURL

shellscript

curl "https://api.x.com/2/tweets/search/recent?\
query=python&\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Available expansions

Expansion	Returns
author_id	Author’s user object
attachments.media_keys	Attached media objects
attachments.poll_ids	Attached poll objects
referenced_tweets.id	Quoted or replied-to Posts
geo.place_id	Place objects
entities.mentions.username	Mentioned user objects

Fields and expansions guide

Learn more about customizing responses

---

Pagination

Search endpoints return results in pages. Use the next_token from the response to fetch additional pages.

How it works

1. Make your initial request with max_results
2. Check the meta object for next_token
3. Include next_token in subsequent requests
4. Repeat until no next_token is returned

Example

cURL

shellscript

# First request
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Subsequent request with pagination token
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100&next_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Pagination guide

Learn more about pagination

---

Post edits

Posts can be edited up to 5 times within 30 minutes. The search endpoints always return the most recent version.

Considerations

• edit_history_tweet_ids contains all Post IDs (oldest first)
• Posts fetched after the 30-minute window represent the final version
• For near-real-time use cases, recently-published Posts may still be edited

Edit Posts fundamentals

Learn more about Post edits

---

Best practices

Start specific

Use multiple operators to narrow results and reduce noise.

Test iteratively

Start broad, then refine based on results.

Handle pagination

Implement proper pagination for large result sets.

Cache results

Store results locally to avoid repeated requests.

---

Next steps

Build a query

Master query syntax

Operator reference

All available operators

Pagination

Handle large result sets

API Reference

Full endpoint documentation