API Consistency

Consistent patterns across X API v2 endpoints

X API v2 is designed with consistent patterns across all endpoints. Once you learn how one endpoint works, the same patterns apply everywhere.

---

Consistent patterns

URL structure

All v2 endpoints follow a predictable pattern:

/version/resource/{id}?parameters
/version/resource/verb?parameters

Examples:

/2/tweets/1234567890                    # Get a specific post
/2/tweets/search/recent                 # Search recent posts
/2/users/by/username/xdevelopers        # Get user by username
/2/users/1234/followers                 # Get user's followers

Response structure

All responses use the same top-level structure:

{
  "data": { ... },       // Primary object(s)
  "includes": { ... },   // Expanded objects
  "meta": { ... },       // Pagination, counts
  "errors": [ ... ]      // Partial errors (if any)
}

ID format

All IDs are returned as strings to ensure language compatibility:

{
  "id": "1234567890123456789",
  "author_id": "2244994945"
}

---

Fields and expansions

The same fields and expansions parameters work consistently:

Object	Fields parameter	Works across
Post	tweet.fields	All endpoints returning posts
User	user.fields	All endpoints returning users
Media	media.fields	All endpoints with media expansions
Poll	poll.fields	All endpoints with poll expansions
Place	place.fields	All endpoints with place expansions

---

Object schemas

The same object type has the same fields regardless of which endpoint returns it:

• A Post from search has the same fields as a Post from lookup
• A User from followers has the same fields as a User from search
• Expanded objects match their standalone counterparts

---

Authentication

All endpoints use the same authentication methods:

Method	Header format
Bearer Token	Authorization: Bearer {token}
OAuth 1.0a	Authorization: OAuth {parameters}
OAuth 2.0	Authorization: Bearer {user_token}

---

Error handling

Errors follow a consistent format:

{
  "title": "Invalid Request",
  "detail": "The query parameter is missing",
  "type": "https://api.x.com/2/problems/invalid-request"
}

See all error types →

---

Pagination

All paginated endpoints use the same token system:

Parameter	Description
max_results	Results per page
pagination_token	Token from next_token or previous_token

Learn more about pagination →

---

Naming conventions

• American English spelling (favorites not favourites)
• Snake_case for field names (author_id, created_at)
• Consistent terminology (retweet_count, not repost_count in fields)

---

Empty values

Fields with no value are omitted rather than returned as null:

// User without a bio
{
  "id": "1234",
  "name": "Example User",
  "username": "example"
  // "description" is omitted, not null
}

---

Entity consistency

The entities object only contains entities parsed from text:

• urls
• hashtags
• mentions
• cashtags

Media and polls are in attachments, not entities.

---

What this means for you

Learn once, use everywhere

Patterns you learn on one endpoint apply to all endpoints.

Predictable responses

Same object types have same structures across the API.

Simpler code

Build reusable functions for common patterns.

Easier debugging

Consistent error formats simplify troubleshooting.

---

Report inconsistencies

Found an inconsistency? Let us know:

• Developer Forum
• Developer Feedback