Integration Guide

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

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get a single Post by ID
response = client.posts.get("1234567890")
print(response.data)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.posts.get("1234567890");
console.log(response.data);

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Get a Post with additional fields and expansions
response = client.posts.get(
    "1234567890",
    tweet_fields=["created_at", "public_metrics", "entities"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"]
)

print(response.data)
print(response.includes)  # Contains expanded user and media objects

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.posts.get("1234567890", {
  tweetFields: ["created_at", "public_metrics", "entities"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
});

console.log(response.data);
console.log(response.includes); // Contains expanded user and media objects

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

​Authentication

​App-Only authentication

​User Context authentication

​Fields and expansions

​Default response

​Available fields

​Example with fields

​Post edits

​How it works

​Example response

​Error handling

​Common errors

​Deleted or protected Posts

​Best practices

Batch requests

Request only needed fields

Cache responses

Handle edits

​Next steps

API Reference

Data dictionary

Sample code

Error handling

Authentication

App-Only authentication

User Context authentication

Fields and expansions

Default response

Available fields

Example with fields

Post edits

How it works

Example response

Error handling

Common errors

Deleted or protected Posts

Best practices

Next steps