X Lists API
Endpoints related to retrieving, managing Lists — 9 operation(s) in the X-published contract.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/x-lists-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
description: X API v2 core endpoints
version: '2.168'
title: X API v2 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://docs.x.com/x-api/lists/introduction
paths:
/2/lists:
post:
security:
- OAuth2UserToken:
- list.write
- tweet.read
- users.read
- list.read
- UserToken: []
tags:
- Lists
summary: Create Lists
operationId: createLists
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateListsRequest'
required: true
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/lists/{id}:
delete:
security:
- OAuth2UserToken:
- users.read
- list.write
- tweet.read
- UserToken: []
tags:
- Lists
summary: 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
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- list.read
- UserToken: []
- BearerToken: []
tags:
- Lists
summary: Get Lists by ID
operationId: getListsById
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
- $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/GetListsByIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
put:
security:
- OAuth2UserToken:
- list.write
- users.read
- tweet.read
- UserToken: []
tags:
- Lists
summary: 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
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateListsRequest'
required: true
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateListsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/lists/{id}/followers:
get:
security:
- OAuth2UserToken:
- list.read
- users.read
- tweet.read
- UserToken: []
- BearerToken: []
tags:
- Lists
summary: Get Lists Followers
operationId: getListsFollowers
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A 64-bit signed integer.
required: false
schema:
type: string
style: form
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/PostFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetListsFollowersResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/lists/{id}/members:
get:
security:
- OAuth2UserToken:
- tweet.read
- list.read
- users.read
- UserToken: []
- BearerToken: []
tags:
- Lists
summary: Get Lists Members
operationId: getListsMembers
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A 64-bit signed integer.
required: false
schema:
type: string
style: form
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/PostFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetListsMembersResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
post:
security:
- OAuth2UserToken:
- list.write
- users.read
- tweet.read
- UserToken: []
tags:
- Lists
summary: Add Lists Member
operationId: addListsMember
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddListsMemberRequest'
required: true
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/AddListsMemberResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/lists/{id}/members/{user_id}:
delete:
security:
- OAuth2UserToken:
- list.write
- users.read
- tweet.read
- UserToken: []
tags:
- Lists
summary: Remove a List member
description: Removes a User from a List by their 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
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
- name: user_id
in: path
required: true
schema:
$ref: '#/components/schemas/UserId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveListsMemberByUserIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/lists/{id}/tweets:
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- list.read
- UserToken: []
- BearerToken: []
tags:
- Lists
summary: Get Lists Posts
operationId: getListsPosts
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/ListId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetListsPostsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
parameters:
UserExpansionsParameter:
name: expansions
in: query
description: A comma separated list of fields to expand.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- affiliation
- most_recent_post_id
- pinned_post_id
explode: false
style: form
MediaFieldsParameter:
name: media.fields
in: query
description: A comma separated list of Media fields to display.
required: false
schema:
type: array
description: The fields available for a Media object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- alt_text
- duration_ms
- height
- media_key
- non_public_metrics
- organic_metrics
- preview_image_url
- promoted_metrics
- public_metrics
- type
- url
- variants
- width
explode: false
style: form
ListFieldsParameter:
name: list.fields
in: query
description: A comma separated list of List fields to display.
required: false
schema:
type: array
description: The fields available for a List object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- created_at
- description
- follower_count
- id
- member_count
- name
- private
explode: false
style: form
PlaceFieldsParameter:
name: place.fields
in: query
description: A comma separated list of Place fields to display.
required: false
schema:
type: array
description: The fields available for a Place object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- contained_within
- country
- country_code
- full_name
- geo
- id
- name
- place_type
explode: false
style: form
ListExpansionsParameter:
name: expansions
in: query
description: A comma separated list of fields to expand.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- owner_id
explode: false
style: form
PollFieldsParameter:
name: poll.fields
in: query
description: A comma separated list of Poll fields to display.
required: false
schema:
type: array
description: The fields available for a Poll object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- duration_minutes
- end_datetime
- id
- options
- voting_status
explode: false
style: form
PostExpansionsParameter:
name: expansions
in: query
description: A comma separated list of fields to expand.
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- article.cover_media
- article.media_entities
- attachments.media_keys
- attachments.media_source_tweet
- attachments.poll_ids
- author_id
- edit_history_post_ids
- entities.mentions.username
- geo.place_id
- in_reply_to_user_id
- referenced_posts
- username
explode: false
style: form
PostFieldsParameter:
name: post.fields
in: query
description: A comma separated list of Post fields to display.
required: false
schema:
type: array
description: The fields available for a Post object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- article
- article_title
- attachments
- card_uri
- community_id
- context_annotations
- conversation_id
- created_at
- display_text_range
- edit_controls
- entities
- geo
- id
- lang
- matched_media_notes
- media_metadata
- non_public_metrics
- note_post
- note_request_suggestions
- organic_metrics
- paid_partnership
- possibly_sensitive
- promoted_metrics
- public_metrics
- reply_settings
- scopes
- source
- suggested_source_links
- suggested_source_links_with_counts
- text
- withheld
explode: false
style: form
UserFieldsParameter:
name: user.fields
in: query
description: A comma separated list of User fields to display.
required: false
schema:
type: array
description: The fields available for a User object.
minItems: 1
uniqueItems: true
items:
type: string
enum:
- confirmed_email
- connection_status
- created_at
- description
- entities
- id
- is_identity_verified
- location
- name
- parody
- profile_banner_url
- profile_image_url
- protected
- public_metrics
- receives_your_dm
- subscriber_count
- subscribes_to_you
- subscription
- subscription_type
- url
- username
- verified
- verified_followers_count
- verified_type
- withheld
explode: false
style: form
schemas:
FieldHydrationFailureProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/field-hydration-failure
DeleteListsResponse:
type: object
properties:
data:
$ref: '#/components/schemas/DeleteListsResponseData'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
GetListsPostsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Post'
errors:
type: array
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
meta:
type: object
properties:
next_token:
type: string
description: Pagination token for the next page of results.
previous_token:
type: string
description: Pagination token for the previous page of results.
result_count:
type: integer
description: Number of items in the data array.
format: int32
Poll:
type: object
properties:
duration_minutes:
type: integer
end_datetime:
type: string
id:
type: string
options:
$ref: '#/components/schemas/PollOptions'
voting_status:
type: string
UserWithheld:
type: object
description: Withholding details for withheld content.
properties:
country_codes:
type:
- array
- 'null'
description: A list of countries (as ISO 3166-1 alpha-2 codes) where this content is withheld.
items:
type: string
scope:
type:
- string
- 'null'
description: The scope of the withholding. Only present, with the value "user", when the entire User is withheld.
enum:
- user
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
ResourceUnavailableProblem:
type: object
required:
- type
- title
- detail
- resource_type
properties:
detail:
type: string
resource_id:
type: string
resource_type:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/resource-unavailable
UserEntities:
type: object
description: A list of metadata found in the User's profile description.
properties:
description:
type:
- object
- 'null'
description: Entities found in the User's bio.
properties:
cashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
hashtags:
type:
- array
- 'null'
items:
type: object
description: A hashtag or cashtag entity.
required:
- start
- end
- tag
properties:
end:
type: integer
description: End index in the text (exclusive).
format: int64
start:
type: integer
description: Start index in the text (inclusive).
format: int64
tag:
type: string
mentions:
type:
- array
- 'null'
items:
type: object
description: A user mention entity.
required:
- start
- end
- username
properties:
end:
type: integer
format: int64
id:
type:
- string
- 'null'
start:
type: integer
format: int64
username:
type: string
urls:
type:
- array
- 'null'
items:
type: object
description: A URL entity found in profile text.
required:
- start
- end
- url
properties:
description:
type:
- string
- 'null'
description: Description of the linked page, when available.
display_url:
type:
- string
- 'null'
description: The URL as displayed in the Post text.
end:
type: integer
format: int64
expanded_url:
type:
- string
- 'null'
description: The fully resolved URL.
images:
type:
- array
- 'null'
items:
type: object
description: A preview image for a linked page.
properties:
height:
type:
- integer
- 'null'
format: int64
url:
type:
- string
- 'null'
width:
type:
- integer
- 'null'
format: int64
media_key:
type:
- string
- 'null'
start:
type: integer
format: int64
status:
type:
- integer
- 'null'
description: HTTP status from resolving the URL.
format: int64
title:
type:
- string
- 'null'
description: Title of the linked page, when available.
unwound_url:
type:
- string
- 'null'
description: The final destination after following redirects.
url:
type: string
description: The t.co shortened URL.
url:
type:
- object
- 'null'
description: Entities for the User's profile website URL.
properties:
urls:
type:
- array
- 'null'
items:
type: object
description: A URL entity found in profile text.
required:
- start
- end
- url
properties:
description:
type:
- string
- 'null'
description: Description of the linked page, when available.
display_url:
type:
- string
- 'null'
description: The URL as displayed in the Post text.
end:
type: integer
format: int64
expanded_url:
type:
- string
- 'null'
description: The fully resolved URL.
images:
type:
- array
- 'null'
items:
type: object
description: A preview image for a linked page.
properties:
height:
type:
- integer
- 'null'
format: int64
url:
type:
- string
- 'null'
width:
type:
- integer
- 'null'
format: int64
media_key:
type:
- string
- 'null'
start:
type: integer
format: int64
status:
type:
- integer
- 'null'
description: HTTP status from resolving the URL.
format: int64
title:
type:
- string
- 'null'
description: Title of the linked page, when available.
unwound_url:
type:
- string
- 'null'
description: The final destination after following redirects.
url:
type: string
description: The t.co shortened URL.
PostMediaMetadata:
type: array
description: Metadata for media attached to this Post.
items:
type: object
description: Metadata for one media item attached to this Post.
properties:
alt_text:
type:
- string
- 'null'
description: Alternative text describing the media for accessibility.
description:
type:
- string
- 'null'
description: Description of the media.
media_key:
type:
- string
- 'null'
description: The unique identifier of the media.
title:
type:
- string
- 'null'
description: Title of the media.
InternalErrorProblem:
type: object
required:
- type
- title
- detail
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/internal-error
PostEditControls:
type: object
description: Indicates how much longer (if at all) this Post can be edited.
properties:
editable_until:
type:
- string
- 'null'
description: The time until which this Post can be edited.
edits_remaining:
type:
- integer
- 'null'
description: Number of edits still allowed for this Post.
format: int64
is_edit_eligible:
type:
- boolean
- 'null'
description: Indicates whether this Post is eligible to be edited.
UserAffiliation:
type: object
description: Metadata about a user's affiliation.
properties:
badge_url:
type:
- string
- 'null'
description: URL of the affiliation badge image shown on the User's profile.
description:
type:
- string
- 'null'
description: Description of the affiliation.
url:
type:
- string
- 'null'
description: URL associated with the affiliation.
user_id:
type:
- array
- 'null'
description: A list of unique identifiers of the accounts this User is affiliated with.
items:
type: string
Problem:
oneOf:
- $ref: '#/components/schemas/ResourceNotFoundProblem'
- $ref: '#/components/schemas/InvalidRequestProblem'
- $ref: '#/components/schemas/NotAuthorizedForResourceProblem'
- $ref: '#/components/schemas/NotAuthorizedForFieldProblem'
- $ref: '#/components/schemas/FieldUnauthorizedProblem'
- $ref: '#/components/schemas/FieldHydrationFailureProblem'
- $ref: '#/components/schemas/ResourceUnavailableProblem'
- $ref: '#/components/schemas/DisallowedResourceProblem'
- $ref: '#/components/schemas/InternalErrorProblem'
discriminator:
propertyName: type
mapping:
https://api.x.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.x.com/2/problems/field-hydration-failure: '#/components/schemas/FieldHydrationFailureProblem'
https://api.x.com/2/problems/field-unauthorized: '#/components/schemas/FieldUnauthorizedProblem'
https://api.x.com/2/problems/internal-error: '#/components/schemas/InternalE
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/x/refs/heads/main/openapi/x-lists-api-openapi.yml