Docs
Lists & Communities
Lists & Communities
Access Twitter Lists, Communities, and member information with comprehensive data about members, moderators, and content.
Overview
The Lists & Communities endpoints provide access to Twitter Lists and Communities - two powerful features for organizing and curating content. Lists allow users to create curated timelines of specific accounts, while Communities are topic-based discussion groups with moderation features.
Key Features
Lists:
- List Management: Get list details, members, and tweets
- User Lists: Find all lists for a user
- List Search: Discover public lists
- Member Access: Get complete member information
Communities:
- Community Details: Get community information and rules
- Member Management: Access members, moderators, and admins
- Community Tweets: Get tweets posted in communities
- Search: Find communities by topic or name
Lists vs Communities
| Feature | Lists | Communities |
|---|---|---|
| Purpose | Curated account timelines | Topic-based discussions |
| Content | Tweets from list members | Tweets posted in community |
| Privacy | Can be public or private | Can be public or invite-only |
| Moderation | No moderation features | Full moderation system |
| Membership | Follow list to see content | Join community to participate |
| Use Case | Organize accounts to follow | Create discussion groups |
Authentication
All endpoints require authentication via the X-API-KEY header:
X-API-KEY: YOUR_API_KEYFor detailed authentication information, see our Authentication Guide.
Lists
Get List by ID
Retrieves detailed information about a Twitter List, including owner, member count, description, and privacy settings.
Endpoint: GET /list/{list_id}
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | Yes | The unique List ID |
Request Examples
curl --request GET \
--url 'https://<direct.gateway>/list/1234567890123456789' \
--header 'X-API-KEY: YOUR_API_KEY'JavaScript:
const response = await fetch('https://<direct.gateway>/list/1234567890123456789', {
headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const list = await response.json();Response Example
{
"id": "1234567890123456789",
"name": "Tech Leaders",
"description": "Influential people in tech",
"created_at": "2020-05-15T10:30:00.000Z",
"owner": {
"id": "987654321",
"username": "tech_curator",
"name": "Tech Curator",
"verified": true
},
"member_count": 156,
"follower_count": 5234,
"private": false,
"pinned": false
}Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique List ID |
name | string | List name |
description | string | List description |
member_count | integer | Number of accounts in list |
follower_count | integer | Number of users following the list |
private | boolean | Whether list is private |
owner | object | List owner information |
Access Rights
- Public Lists: Accessible to everyone
- Private Lists: Only accessible to the owner and accounts with appropriate permissions
- 403 Forbidden: Returned when accessing private lists without permission
Get List Members
Retrieves all members of a List with their complete user information. Useful for understanding who is included in a curated list.
Endpoint: GET /list/{list_id}/members
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | Yes | The List ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of results (Default: 100, Max: 1000) |
cursor | string | No | Pagination cursor |
Request Examples
curl --request GET \
--url 'https://<direct.gateway>/list/1234567890123456789/members?limit=100' \
--header 'X-API-KEY: YOUR_API_KEY'JavaScript:
async function getAllListMembers(listId) {
let allMembers = [];
let cursor = null;
do {
const url = `/list/${listId}/members?limit=1000${cursor ? `&cursor=${cursor}` : ''}`;
const response = await fetch(url, {
headers: { 'X-API-KEY': API_KEY }
});
const data = await response.json();
allMembers = allMembers.concat(data.data);
cursor = data.meta?.next_cursor || null;
} while (cursor);
return allMembers;
}Response Example
{
"data": [
{
"id": "111222333",
"username": "tech_leader",
"name": "Tech Leader",
"verified": true,
"profile_image_url": "https://pbs.twimg.com/profile_images/...",
"metrics": {
"followers_count": 152340,
"following_count": 523
},
"added_at": "2023-06-10T14:20:00.000Z"
}
],
"meta": {
"result_count": 100,
"next_cursor": "eyJpZCI6IjExMTIyMjMzMyJ9"
}
}Use Cases
- List Analysis: Understand the composition of a list
- Influencer Discovery: Find influential accounts in specific lists
- Content Curation: Use lists to discover accounts to follow
Get List Tweets
Retrieves tweets from all members of a List. This creates a curated timeline of content from the list members.
Endpoint: GET /list/{list_id}/tweets
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
list_id | string | Yes | The List ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of results (Default: 20, Max: 100) |
cursor | string | No | Pagination cursor |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/list/1234567890123456789/tweets?limit=20' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "1234567890123456789",
"text": "Tweet from list member",
"author": {
"id": "111222333",
"username": "tech_leader",
"in_list": true
},
"created_at": "2024-10-01T12:00:00.000Z",
"metrics": {
"like_count": 523,
"retweet_count": 87
}
}
],
"meta": {
"result_count": 20,
"next_cursor": "..."
}
}Use Cases
- Curated Feeds: Create custom feeds from list members
- Content Aggregation: Aggregate content from specific accounts
- Topic Monitoring: Monitor tweets from a curated group
Get User Lists
Retrieves all Lists for a user, including lists they own and lists they follow.
Endpoint: GET /user/{user_id}/lists
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | The user ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
type | string | No | Filter: owned, subscribed, all (Default: all) |
limit | integer | No | Number of results (Default: 20, Max: 100) |
Request Examples
# All lists
curl --request GET \
--url 'https://<direct.gateway>/user/987654321/lists?type=all&limit=20' \
--header 'X-API-KEY: YOUR_API_KEY'
# Only owned lists
curl --request GET \
--url 'https://<direct.gateway>/user/987654321/lists?type=owned' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"owned_lists": [
{
"id": "1234567890123456789",
"name": "My Tech List",
"member_count": 156,
"follower_count": 42,
"private": false
}
],
"subscribed_lists": [
{
"id": "9876543210987654321",
"name": "News Sources",
"owner": {
"username": "curator",
"name": "News Curator"
},
"member_count": 89
}
]
}Search Lists
Searches for public Lists by name or description. Useful for discovering relevant lists.
Endpoint: GET /lists/search
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search term |
limit | integer | No | Number of results (Default: 20, Max: 100) |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/lists/search?q=technology&limit=20' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "1234567890123456789",
"name": "AI Researchers",
"description": "Leading AI researchers and scientists",
"owner": {
"username": "ai_curator",
"verified": false
},
"member_count": 234,
"follower_count": 1523
}
],
"meta": {
"result_count": 15
}
}Communities
Get Community by ID
Retrieves detailed information about a Twitter Community, including description, rules, member count, and moderation settings.
Endpoint: GET /community/{community_id}
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
community_id | string | Yes | The Community ID |
Request Examples
curl --request GET \
--url 'https://<direct.gateway>/community/1234567890123456789' \
--header 'X-API-KEY: YOUR_API_KEY'JavaScript:
const response = await fetch('https://<direct.gateway>/community/1234567890123456789', {
headers: { 'X-API-KEY': 'YOUR_API_KEY' }
});
const community = await response.json();Response Example
{
"id": "1234567890123456789",
"name": "Tech Enthusiasts",
"description": "A community for tech lovers",
"created_at": "2021-09-01T10:00:00.000Z",
"admin": {
"id": "987654321",
"username": "community_admin",
"name": "Admin User",
"verified": true
},
"member_count": 5234,
"rules": [
"Be respectful",
"No spam",
"Stay on topic"
],
"theme": {
"primary_color": "#1DA1F2",
"banner_url": "https://..."
},
"purpose": "general",
"invite_only": false
}Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique Community ID |
name | string | Community name |
description | string | Community description |
member_count | integer | Number of members |
admin | object | Community admin information |
rules | array | Community rules |
purpose | string | Community purpose/category |
invite_only | boolean | Whether community requires invitation |
Access Rights
- Public Communities: Accessible to everyone
- Invite-Only Communities: Only accessible to members
- 403 Forbidden: Returned when accessing invite-only communities without membership
Get Community Members
Retrieves members of a Community, with optional filtering by role (admin, moderator, member).
Endpoint: GET /community/{community_id}/members
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
community_id | string | Yes | The Community ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
role | string | No | Filter: admin, moderator, member |
limit | integer | No | Number of results (Default: 100, Max: 1000) |
Request Examples
# All members
curl --request GET \
--url 'https://<direct.gateway>/community/1234567890123456789/members?limit=100' \
--header 'X-API-KEY: YOUR_API_KEY'
# Only moderators
curl --request GET \
--url 'https://<direct.gateway>/community/1234567890123456789/members?role=moderator' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "111222333",
"username": "member_user",
"name": "Member Name",
"role": "member",
"joined_at": "2023-03-15T14:20:00.000Z",
"profile_image_url": "https://pbs.twimg.com/profile_images/..."
}
],
"meta": {
"total_members": 5234,
"admins": 3,
"moderators": 12,
"members": 5219
}
}Member Roles
- Admin: Community creators and administrators
- Moderator: Users with moderation permissions
- Member: Regular community members
Get Community Tweets
Retrieves tweets posted in a Community. This shows the discussion content within the community.
Endpoint: GET /community/{community_id}/tweets
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
community_id | string | Yes | The Community ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of results (Default: 20, Max: 100) |
sort | string | No | Sort order: recent, top (Default: recent) |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/community/1234567890123456789/tweets?limit=20&sort=top' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "1234567890123456789",
"text": "Community tweet content",
"author": {
"id": "111222333",
"username": "community_member",
"community_role": "member"
},
"created_at": "2024-10-01T12:00:00.000Z",
"community": {
"id": "1234567890123456789",
"name": "Tech Enthusiasts"
},
"metrics": {
"like_count": 45,
"retweet_count": 12
}
}
]
}Get User Communities
Retrieves all Communities a user belongs to, with their role in each community.
Endpoint: GET /user/{user_id}/communities
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | The user ID |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
role | string | No | Filter: admin, moderator, member |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/user/987654321/communities' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "1234567890123456789",
"name": "Tech Enthusiasts",
"user_role": "member",
"member_count": 5234,
"joined_at": "2023-03-15T14:20:00.000Z"
}
],
"meta": {
"result_count": 3
}
}Search Communities
Searches for public Communities by name, description, or topic.
Endpoint: GET /communities/search
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Yes | Search term |
category | string | No | Category filter |
limit | integer | No | Number of results (Default: 20, Max: 100) |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/communities/search?q=technology&limit=20' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"data": [
{
"id": "1234567890123456789",
"name": "AI & Machine Learning",
"description": "Discuss AI and ML topics",
"member_count": 12340,
"purpose": "technology",
"invite_only": false
}
],
"meta": {
"result_count": 8
}
}Get Community Rules
Retrieves the rules and moderation policies of a Community.
Endpoint: GET /community/{community_id}/rules
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
community_id | string | Yes | The Community ID |
Request Example
curl --request GET \
--url 'https://<direct.gateway>/community/1234567890123456789/rules' \
--header 'X-API-KEY: YOUR_API_KEY'Response Example
{
"community_id": "1234567890123456789",
"rules": [
{
"id": "rule_1",
"title": "Be respectful",
"description": "Treat all members with respect",
"priority": 1
},
{
"id": "rule_2",
"title": "No spam",
"description": "Do not post spam or self-promotion",
"priority": 2
}
],
"enforcement": {
"warnings_before_ban": 3,
"moderator_approval_required": false
}
}Community Purposes/Categories
Communities can be categorized by purpose:
| Purpose | Description |
|---|---|
general | General discussions |
technology | Technology & Innovation |
gaming | Gaming & Esports |
entertainment | Entertainment & Media |
sports | Sports & Fitness |
education | Education & Learning |
business | Business & Career |
Best Practices
Lists & Communities-Specific Tips
- Handle private resources: Always check for 403 errors when accessing lists/communities
- Use pagination: Lists can have thousands of members - always use cursor-based pagination
- Cache list data: Lists and communities don't change frequently, cache for 5-10 minutes
- Distinguish Lists vs Communities: Lists are curated timelines, Communities are discussion groups
For general API best practices including error handling, rate limits, and performance optimization, see our Best Practices Guide.
3. Cache List/Community Data
Cache data to reduce API calls:
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
async function getCachedList(listId) {
const cached = cache.get(listId);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const response = await fetch(`/list/${listId}`, {
headers: { 'X-API-KEY': API_KEY }
});
const data = await response.json();
cache.set(listId, { data, timestamp: Date.now() });
return data;
}For comprehensive error handling and rate limits information, see our guides:
- Error Handling Guide - Complete error handling reference
- Rate Limits Guide - Rate limit details and management
Troubleshooting
| Issue | Symptoms | Possible Causes | Solutions |
|---|---|---|---|
| Cannot access private list | Getting 403 errors for lists | List is private, API credentials don't have access | Check if list is private, ensure your API credentials have appropriate permissions, use public lists for testing |
| Incomplete member lists | Not getting all members | Not using pagination, hitting rate limits, private members not accessible | Implement proper cursor-based pagination, check rate limit headers, be aware that some members may be private - see Pagination Guide |
FAQ
What's the difference between Lists and Communities?
- Lists: Curated timelines of accounts you want to follow together
- Communities: Discussion groups with moderation, rules, and topic-based content
Can I create lists or communities via the API?
Currently, the API provides read-only access. Creation and management must be done through Twitter's interface.
How do I find lists for a specific topic?
Use the /lists/search endpoint with relevant keywords.
Are community members public?
Public communities show member lists. Invite-only communities may restrict member visibility.
Can I get tweets from multiple lists at once?
No, you need to make separate requests for each list. Consider caching and batching requests.
Related Documentation
- Users Endpoints - Get user information
- Tweets Endpoints - Get tweet details
- Using Pagination Cursors - Pagination guide
- Error Handling Guide - Error handling
- Rate Limits Guide - Rate limits
- Best Practices - API best practices