Lists & Communities – Twitter API

Docs

Lists & Communities

Access Twitter Lists, Communities, and member information.

Overview

The Lists & Communities endpoints provide access to Twitter Lists, Community data, and their members.

Lists

Get List by ID

Retrieves details about a Twitter List.

GET /list/{list_id}

Parameters

Name	Type	Required	Description
`list_id`	string	Yes	The unique List ID

Headers

X-API-KEY: <YOUR_API_KEY>

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
}

Get List Members

Retrieves all members of a List.

GET /list/{list_id}/members

Parameters

Name	Type	Required	Description
`list_id`	string	Yes	The List ID
`limit`	integer	No	Number of results (Default: 100, Max: 1000)
`cursor`	string	No	Cursor for pagination

Response Example

{
  "data": [
    {
      "id": "111222333",
      "username": "tech_leader",
      "name": "Tech Leader",
      "verified": true,
      "profile_image_url": "https://...",
      "metrics": {
        "followers_count": 152340,
        "following_count": 523
      },
      "added_at": "2023-06-10T14:20:00.000Z"
    }
  ],
  "meta": {
    "result_count": 100,
    "next_cursor": "eyJpZCI6IjExMTIyMjMzMyJ9"
  }
}

Get List Tweets

Retrieves tweets from List members.

GET /list/{list_id}/tweets

Parameters

Name	Type	Required	Description
`list_id`	string	Yes	The List ID
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`cursor`	string	No	Cursor for pagination

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": {...}
    }
  ],
  "meta": {
    "result_count": 20,
    "next_cursor": "..."
  }
}

Get User Lists

Retrieves all Lists for a user (owned or subscribed).

GET /user/{user_id}/lists

Parameters

Name	Type	Required	Description
`user_id`	string	Yes	The user ID
`type`	string	No	`owned`, `subscribed`, `all` (Default: all)
`limit`	integer	No	Number of results (Default: 20, Max: 100)

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.

GET /lists/search

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search term
`limit`	integer	No	Number of results (Default: 20, Max: 100)

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "name": "AI Researchers",
      "description": "Leading AI researchers and scientists",
      "owner": {...},
      "member_count": 234,
      "follower_count": 1523
    }
  ],
  "meta": {
    "result_count": 15
  }
}

Communities

Get Community by ID

Retrieves details about a Twitter Community.

GET /community/{community_id}

Parameters

Name	Type	Required	Description
`community_id`	string	Yes	The Community ID

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"
  },
  "member_count": 5234,
  "rules": [
    "Be respectful",
    "No spam",
    "Stay on topic"
  ],
  "theme": {
    "primary_color": "#1DA1F2",
    "banner_url": "https://..."
  },
  "purpose": "general",
  "invite_only": false
}

Get Community Members

Retrieves members of a Community.

GET /community/{community_id}/members

Parameters

Name	Type	Required	Description
`community_id`	string	Yes	The Community ID
`role`	string	No	`admin`, `moderator`, `member`
`limit`	integer	No	Number of results (Default: 100, Max: 1000)

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://..."
    }
  ],
  "meta": {
    "total_members": 5234,
    "admins": 3,
    "moderators": 12,
    "members": 5219
  }
}

Get Community Tweets

Retrieves tweets from a Community.

GET /community/{community_id}/tweets

Parameters

Name	Type	Required	Description
`community_id`	string	Yes	The Community ID
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`sort`	string	No	`recent`, `top` (Default: recent)

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": {...}
    }
  ]
}

Get User Communities

Retrieves all Communities for a user.

GET /user/{user_id}/communities

Parameters

Name	Type	Required	Description
`user_id`	string	Yes	The user ID
`role`	string	No	`admin`, `moderator`, `member`

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.

GET /communities/search

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search term
`category`	string	No	Category
`limit`	integer	No	Number of results (Default: 20, Max: 100)

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 of a Community.

GET /community/{community_id}/rules

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

Purpose	Description
`general`	General discussions
`technology`	Technology & Innovation
`gaming`	Gaming & Esports
`entertainment`	Entertainment & Media
`sports`	Sports & Fitness
`education`	Education & Learning
`business`	Business & Career

Rate Limits

Basic Plan: 100 Requests/hour
Pro Plan: 1,000 Requests/hour
Enterprise Plan: 10,000 Requests/hour

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API Key
403	Forbidden - Access to private List/Community denied
404	Not Found - List/Community does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error