Skip to main content
This guide covers the key concepts you need to integrate the List lookup endpoints into your application.

​
Authentication

List lookup endpoints support multiple authentication methods:
MethodBest forAccess to private Lists?
OAuth 2.0 App-OnlyPublic List dataNo
OAuth 2.0 Authorization Code with PKCEUser-facing appsYes (owned/followed)
OAuth 1.0a User ContextLegacy integrationsYes (owned/followed)

​
Example request

cURL
curl "https://api.x.com/2/lists/84839422?\
list.fields=description,member_count,follower_count,private" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
Endpoints overview

MethodEndpointDescription
GET/2/lists/:idGet List by ID
GET/2/users/:id/owned_listsGet Lists owned by a user

​
Fields and expansions

​
Default response

{
  "data": {
    "id": "84839422",
    "name": "Tech News"
  }
}

​
Available fields

FieldDescription
created_atList creation timestamp
descriptionList description
follower_countNumber of followers
member_countNumber of members
owner_idOwner’s user ID
privateWhether List is private
FieldDescription
usernameOwner’s @handle
nameOwner’s display name
verifiedOwner’s verification status
profile_image_urlOwner’s avatar URL

​
Example with expansions

cURL
curl "https://api.x.com/2/lists/84839422?\
list.fields=description,member_count,follower_count,owner_id&\
expansions=owner_id&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
Response with expansion

{
  "data": {
    "id": "84839422",
    "name": "Tech News",
    "description": "Top tech journalists",
    "member_count": 50,
    "follower_count": 1250,
    "owner_id": "2244994945"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "XDevelopers",
        "verified": true
      }
    ]
  }
}

Fields and expansions guide

Learn more about customizing responses

​
Pagination

When retrieving owned Lists, results are paginated:
cURL
# First request
curl "https://api.x.com/2/users/123/owned_lists?max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Subsequent request with pagination token
curl "https://api.x.com/2/users/123/owned_lists?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Pagination guide

Learn more about pagination

​
Private Lists

  • Private Lists are only visible to the owner
  • You must authenticate as the owner to retrieve private List details
  • The private field indicates whether a List is private

​
Error handling

StatusErrorSolution
400Invalid requestCheck List ID format
401UnauthorizedVerify authentication
403ForbiddenList may be private
404Not FoundList doesn’t exist
429Too Many RequestsWait and retry

​
Next steps

Quickstart

Make your first List lookup request

List Posts

Get Posts from a List

API Reference

Full endpoint documentation

Sample code

Working code examples