Integration Guide

Key concepts and best practices for integrating Post lookup

This guide covers the key concepts you need to integrate the Post lookup endpoints into your application.

---

Authentication

All X API v2 endpoints require authentication. Choose the method that fits your use case:

Method	Best for	Can access private metrics?
OAuth 2.0 App-Only	Server-to-server, public data	No
OAuth 2.0 Authorization Code with PKCE	User-facing apps	Yes (for authorized user’s Posts)
OAuth 1.0a User Context	Legacy integrations	Yes (for authorized user’s Posts)

App-Only authentication

For public Post data, use a Bearer Token:

cURL

shellscript

curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

User Context authentication

To access private metrics, authenticate on behalf of the Post author:

The following fields require User Context authentication:

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

---

Fields and expansions

The X API v2 returns minimal data by default. Use fields and expansions to request exactly what you need.

Default response

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

Available fields

tweet.fields

Field	Description
created_at	Post creation timestamp
author_id	Author’s user ID
public_metrics	Like, retweet, reply, quote counts
entities	Hashtags, mentions, URLs, cashtags
attachments	Media keys, poll IDs
conversation_id	Thread identifier
context_annotations	Topic/entity classifications
in_reply_to_user_id	User being replied to
lang	Detected language
source	Posting client
possibly_sensitive	Sensitive content flag
reply_settings	Who can reply

user.fields (requires author_id expansion)

Field	Description
username	@handle
name	Display name
profile_image_url	Avatar URL
verified	Verification status
description	Bio
public_metrics	Follower/following counts
created_at	Account creation date

media.fields (requires attachments.media_keys expansion)

Field	Description
url	Media URL
preview_image_url	Thumbnail URL
type	photo, video, animated_gif
duration_ms	Video duration
height, width	Dimensions
alt_text	Accessibility text

Example with fields

cURL

shellscript

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

---

Post edits

Posts can be edited up to 5 times within 30 minutes of creation.

How it works

• Each edit creates a new Post ID
• edit_history_tweet_ids contains all versions (oldest first)
• The endpoint always returns the most recent version

Example response

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

Posts retrieved after their 30-minute edit window represent the final version. For real-time use cases, be aware that recently-published Posts may still be edited.

---

Error handling

Common errors

Status	Error	Solution
400	Invalid request	Check parameter formatting
401	Unauthorized	Verify authentication credentials
403	Forbidden	Check App permissions
404	Not Found	Post deleted or doesn’t exist
429	Too Many Requests	Wait and retry (see rate limits)

Deleted or protected Posts

If a Post is deleted or from a protected account you don’t follow:

• Single Post lookup returns 404
• Multi-Post lookup omits the Post from results with an errors array

{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

---

Best practices

Batch requests

Use the multi-Post endpoint to fetch up to 100 Posts at once, reducing API calls.

Request only needed fields

Specify only the fields you need to minimize response size and processing time.

Cache responses

Cache Post data locally to reduce repeated requests for the same content.

Handle edits

For real-time apps, consider re-fetching Posts after the 30-minute edit window.

---

Next steps

API Reference

Complete endpoint documentation

Data dictionary

All available objects and fields

Sample code

Working code examples

Error handling

Handle errors gracefully