Endpoints related to retrieving, managing Lists
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.161'
title: X API v2 Account Activity Lists API
termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
contact:
name: X Developers
url: https://developer.x.com/
license:
name: X Developer Agreement and Policy
url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
url: https://api.x.com
tags:
- name: Lists
description: Endpoints related to retrieving, managing Lists
externalDocs:
description: Find out more
url: https://developer.twitter.com/en/docs/twitter-api/lists
paths:
/2/lists:
post:
security:
- OAuth2UserToken:
- list.read
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Create List
description: Creates a new List for the authenticated user.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/post-lists
operationId: createLists
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListCreateRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListCreateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/lists/{id}:
delete:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Delete List
description: Deletes a specific List owned by the authenticated user by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/delete-lists-id
operationId: deleteLists
parameters:
- name: id
in: path
description: The ID of the List to delete.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListDeleteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get List by ID
description: Retrieves details of a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-lists-id
operationId: getListsById
parameters:
- name: id
in: path
description: The ID of the List.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
- $ref: '#/components/parameters/ListFieldsParameter'
- $ref: '#/components/parameters/ListExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2ListsIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Update List
description: Updates the details of a specific List owned by the authenticated user by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/manage-lists/api-reference/put-lists-id
operationId: updateLists
parameters:
- name: id
in: path
description: The ID of the List to modify.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListUpdateRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListUpdateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/lists/{id}/followers:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get List Followers
description: Retrieves a list of Users who follow a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/users/follows/api-reference/get-users-id-followers
operationId: getListsFollowers
parameters:
- name: id
in: path
description: The ID of the List.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationTokenLong'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2ListsIdFollowersResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/lists/{id}/members:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get List Members
description: Retrieves a list of Users who are members of a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships
operationId: getListsMembers
parameters:
- name: id
in: path
description: The ID of the List.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationTokenLong'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2ListsIdMembersResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Add List Member
description: Adds a User to a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/post-lists-id-members
operationId: addListsMember
parameters:
- name: id
in: path
description: The ID of the List for which to add a member.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListAddUserRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListMutateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/lists/{id}/members/{user_id}:
delete:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Remove List Member
description: Removes a User from a specific List by its ID and the User’s ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/delete-lists-id-members-user_id
operationId: removeListsMemberByUserId
parameters:
- name: id
in: path
description: The ID of the List to remove a member.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
- name: user_id
in: path
description: The ID of User that will be removed from the List.
required: true
schema:
$ref: '#/components/schemas/UserId'
style: simple
example: '1234567890'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListMutateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/lists/{id}/tweets:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get List Posts
description: Retrieves a list of Posts associated with a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-tweets/api-reference/get-lists-id-tweets
operationId: getListsPosts
parameters:
- name: id
in: path
description: The ID of the List.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get the next 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationToken36'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/TweetFieldsParameter'
- $ref: '#/components/parameters/TweetExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2ListsIdTweetsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/followed_lists:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get Followed Lists
description: Retrieves a list of Lists followed by a specific User by their ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/get-users-id-followed_lists
operationId: getUsersFollowedLists
parameters:
- name: id
in: path
description: The ID of the User to lookup.
required: true
example: '2244994945'
schema:
$ref: '#/components/schemas/UserId'
style: simple
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationTokenLong'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/ListFieldsParameter'
- $ref: '#/components/parameters/ListExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2UsersIdFollowedListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Follow List
description: Causes the authenticated user to follow a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/post-users-id-followed-lists
operationId: followList
parameters:
- name: id
in: path
description: The ID of the authenticated source User that will follow the List.
required: true
schema:
$ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
style: simple
example: '1234567890'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListFollowedRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListFollowedResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/followed_lists/{list_id}:
delete:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Unfollow List
description: Causes the authenticated user to unfollow a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-follows/api-reference/delete-users-id-followed-lists-list_id
operationId: unfollowList
parameters:
- name: id
in: path
description: The ID of the authenticated source User that will unfollow the List.
required: true
schema:
$ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
style: simple
example: '1234567890'
- name: list_id
in: path
description: The ID of the List to unfollow.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListFollowedResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/list_memberships:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get List Memberships
description: Retrieves a list of Lists that a specific User is a member of by their ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-members/api-reference/get-users-id-list_memberships
operationId: getUsersListMemberships
parameters:
- name: id
in: path
description: The ID of the User to lookup.
required: true
example: '2244994945'
schema:
$ref: '#/components/schemas/UserId'
style: simple
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationTokenLong'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/ListFieldsParameter'
- $ref: '#/components/parameters/ListExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2UsersIdListMembershipsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/owned_lists:
get:
security:
- BearerToken: []
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get Owned Lists
description: Retrieves a list of Lists owned by a specific User by their ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/list-lookup/api-reference/get-users-id-owned_lists
operationId: getUsersOwnedLists
parameters:
- name: id
in: path
description: The ID of the User to lookup.
required: true
example: '2244994945'
schema:
$ref: '#/components/schemas/UserId'
style: simple
- name: max_results
in: query
description: The maximum number of results.
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
example: 10
- name: pagination_token
in: query
description: This parameter is used to get a specified 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationTokenLong'
style: form
example: next_token_abc123
- $ref: '#/components/parameters/ListFieldsParameter'
- $ref: '#/components/parameters/ListExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2UsersIdOwnedListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/pinned_lists:
get:
security:
- OAuth2UserToken:
- list.read
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Get Pinned Lists
description: Retrieves a list of Lists pinned by the authenticated user.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/get-users-id-pinned_lists
operationId: getUsersPinnedLists
parameters:
- name: id
in: path
description: The ID of the authenticated source User for whom to return results.
required: true
schema:
$ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
style: simple
example: '1234567890'
- $ref: '#/components/parameters/ListFieldsParameter'
- $ref: '#/components/parameters/ListExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Get2UsersIdPinnedListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Pin List
description: Causes the authenticated user to pin a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/post-users-id-pinned-lists
operationId: pinList
parameters:
- name: id
in: path
description: The ID of the authenticated source User that will pin the List.
required: true
schema:
$ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
style: simple
example: '1234567890'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListPinnedRequest'
required: true
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListPinnedResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2/users/{id}/pinned_lists/{list_id}:
delete:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- UserToken: []
tags:
- Lists
summary: X Unpin List
description: Causes the authenticated user to unpin a specific List by its ID.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/lists/pinned-lists/api-reference/delete-users-id-pinned-lists-list_id
operationId: unpinList
parameters:
- name: id
in: path
description: The ID of the authenticated source User for whom to return results.
required: true
schema:
$ref: '#/components/schemas/UserIdMatchesAuthenticatedUser'
style: simple
example: '1234567890'
- name: list_id
in: path
description: The ID of the List to unpin.
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
example: '1234567890'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ListUnpinResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
List:
type: object
description: A X List is a curated group of accounts.
required:
- id
- name
properties:
created_at:
type: string
format: date-time
description:
type: string
follower_count:
type: integer
id:
$ref: '#/components/schemas/ListId'
member_count:
type: integer
name:
type: string
description: The name of this List.
owner_id:
$ref: '#/components/schemas/UserId'
private:
type: boolean
PollId:
type: string
description: Unique identifier of this poll.
pattern: ^[0-9]{1,19}$
example: '1365059861688410112'
Media:
type: object
required:
- type
properties:
height:
$ref: '#/components/schemas/MediaHeight'
media_key:
$ref: '#/components/schemas/MediaKey'
type:
type: string
width:
$ref: '#/components/schemas/MediaWidth'
discriminator:
propertyName: type
mapping:
animated_gif: '#/components/schemas/AnimatedGif'
photo: '#/components/schemas/Photo'
video: '#/components/schemas/Video'
ListPinnedResponse:
type: object
properties:
data:
type: object
properties:
pinned:
type: boolean
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
Geo:
type: object
required:
- type
- bbox
- properties
properties:
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
minimum: -180
maximum: 180
format: double
example:
- -105.193475
- 39.60973
- -105.053164
- 39.761974
geometry:
$ref: '#/components/schemas/Point'
properties:
type: object
type:
type: string
enum:
- Feature
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
ContextAnnotationDomainFields:
type: object
description: Represents the data for the context annotation domain.
required:
- id
properties:
description:
type: string
description: Description of the context annotation domain.
example: Example description for this resource.
id:
type: string
description: The unique id for a context annotation domain.
pattern: ^[0-9]{1,19}$
example: '1234567890'
name:
type: string
description: Name of the context annotation domain.
example: Example User
PreviousToken:
type: string
description: The previous token.
minLength: 1
ListAd
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter/refs/heads/main/openapi/twitter-lists-api-openapi.yml