Xx
Chat

Get Chat Conversations

Changed on

Retrieves a list of Chat conversations for the authenticated user's inbox, newest first: the most recently active conversation comes first. The unread, last_read_event_id and newest_event_id fields give your read state, computed from your latest read receipt and each conversation's latest notifying message. Request them with chat_conversation.fields=unread,last_read_event_id,newest_event_id.

The filters unread_only, type, is_archived, is_muted, participant_ids, participant_query, start_time and end_time are optional, and all filters must match (AND). participant_query keeps conversations where another participant's username, or a word of their display name, starts with the query, ignoring case and accents; with a leading @ it matches usernames only. It considers the 100 people who best match the query, uses only public profile information, and never matches group names, nicknames or messages. start_time and end_time apply to the time of each conversation's latest message.

Each page covers max_results conversations and returns those that match, so a page can hold fewer than max_results, or none, while meta.next_token is set and has_more is true: keep paging, passing meta.next_token as pagination_token. Once a page reaches a conversation whose latest message is older than start_time, has_more is false. A pagination_token only works with the same filters as the request that returned it; with other filters, the request fails with a 400.

When both are provided, start_time must be earlier than end_time.

get/2/chat/conversations

Request

  • Base URL
    https://api.x.com
  • URL
    https://api.x.com/2/chat/conversations
  • Auth
    • OAuth 2
      Authorization code: https://api.x.com/2/oauth2/authorize
      Token URL: https://api.x.com/2/oauth2/token scopes: dm.read, users.read
    • or HTTP oauth

Query parameters

max_resultsinteger

Conversations covered per page (1-1000, default 200). Filtered pages can return fewer.

pagination_tokenstring

meta.next_token from the previous page. Send the same filters with it, or the request fails.

unread_onlyboolean

Return only unread conversations. A page can be short; keep paging while has_more.

type'direct' | 'group'

Only direct (1:1) or only group conversations. Omit for both.

is_archivedboolean

true: only archived; false: only not archived. Omit for both.

is_mutedboolean

true: only muted; false: only not muted. Omit for both.

participant_idsstring[]

Comma-separated numeric user IDs (1-10), all in the chat. Names or @handles: use participant_query.

participant_querystring

Name or @username prefix (1-50 chars); keeps chats where any other participant matches it.

start_timestring date-time

ISO 8601, e.g. 2026-10-16T00:00:00Z. Chats whose latest message is at or after this time.

end_timestring date-time

ISO 8601, e.g. 2026-10-17T00:00:00Z. Chats whose latest message is before this time.

chat_conversation.fieldsstring[]

The fields available for a ChatConversation object.

A comma separated list of ChatConversation fields to display.

expansionsstring[]

A comma separated list of fields to expand.

user.fieldsstring[]

The fields available for a User object.

A comma separated list of User fields to display.

Response

The request has succeeded.

Changes

  • 2e1fefa37444Revision changes
    • breaking

      added to the response body oneOf list for the response status

    • breaking

      added to the / response property oneOf list for the response status

    • info

      added the new optional query request parameter end_time

    • info

      added the new optional query request parameter is_archived

    • info

      added the new optional query request parameter is_muted

    • info

      added the new optional query request parameter participant_ids

    • info

      added the new optional query request parameter participant_query

    • info

      added the new optional query request parameter start_time

    • info

      added the new optional query request parameter type

    • info

      added the enum value receives_your_chat to the property items/ of the query request parameter user.fields

    • info

      added https://api.x.com/2/problems/dm-bad-attachment https://api.x.com/2/problems/dm-bad-cta https://api.x.com/2/problems/dm-bad-custom-profile https://api.x.com/2/problems/dm-bad-media https://api.x.com/2/problems/dm-bad-quick-reply https://api.x.com/2/problems/dm-bad-url https://api.x.com/2/problems/dm-conversation-name-too-long https://api.x.com/2/problems/dm-conversation-not-found https://api.x.com/2/problems/dm-duplicate https://api.x.com/2/problems/dm-inactive-device https://api.x.com/2/problems/dm-not-delivered https://api.x.com/2/problems/dm-not-found https://api.x.com/2/problems/dm-not-owner https://api.x.com/2/problems/dm-participant-not-added https://api.x.com/2/problems/dm-participant-not-found https://api.x.com/2/problems/dm-participant-restricted https://api.x.com/2/problems/dm-participant-unavailable https://api.x.com/2/problems/dm-rate-limited https://api.x.com/2/problems/dm-recipient-blocks-sender https://api.x.com/2/problems/dm-recipient-cannot-receive https://api.x.com/2/problems/dm-recipient-encrypted-unavailable https://api.x.com/2/problems/dm-recipient-not-accepting https://api.x.com/2/problems/dm-recipient-not-found https://api.x.com/2/problems/dm-recipient-restricts-groups https://api.x.com/2/problems/dm-recipient-unavailable https://api.x.com/2/problems/dm-request-in-progress https://api.x.com/2/problems/dm-safety-limited https://api.x.com/2/problems/dm-safety-rejected https://api.x.com/2/problems/dm-sender-blocks-recipient https://api.x.com/2/problems/dm-sender-declined-dms https://api.x.com/2/problems/dm-sender-dms-closed https://api.x.com/2/problems/dm-sender-encrypted-unavailable https://api.x.com/2/problems/dm-sender-not-in-conversation https://api.x.com/2/problems/dm-sender-not-permitted https://api.x.com/2/problems/dm-sender-not-verified https://api.x.com/2/problems/dm-sender-phone-required https://api.x.com/2/problems/dm-sender-read-only https://api.x.com/2/problems/dm-sender-unavailable https://api.x.com/2/problems/dm-text-empty https://api.x.com/2/problems/dm-text-too-long https://api.x.com/2/problems/dm-too-few-participants https://api.x.com/2/problems/dm-too-many-participants https://api.x.com/2/problems/dm-unsupported-message mapping keys to the response discriminator for the response status

    • info

      added the optional property /// to the response with the status

    • info

      added https://api.x.com/2/problems/dm-bad-attachment https://api.x.com/2/problems/dm-bad-cta https://api.x.com/2/problems/dm-bad-custom-profile https://api.x.com/2/problems/dm-bad-media https://api.x.com/2/problems/dm-bad-quick-reply https://api.x.com/2/problems/dm-bad-url https://api.x.com/2/problems/dm-conversation-name-too-long https://api.x.com/2/problems/dm-conversation-not-found https://api.x.com/2/problems/dm-duplicate https://api.x.com/2/problems/dm-inactive-device https://api.x.com/2/problems/dm-not-delivered https://api.x.com/2/problems/dm-not-found https://api.x.com/2/problems/dm-not-owner https://api.x.com/2/problems/dm-participant-not-added https://api.x.com/2/problems/dm-participant-not-found https://api.x.com/2/problems/dm-participant-restricted https://api.x.com/2/problems/dm-participant-unavailable https://api.x.com/2/problems/dm-rate-limited https://api.x.com/2/problems/dm-recipient-blocks-sender https://api.x.com/2/problems/dm-recipient-cannot-receive https://api.x.com/2/problems/dm-recipient-encrypted-unavailable https://api.x.com/2/problems/dm-recipient-not-accepting https://api.x.com/2/problems/dm-recipient-not-found https://api.x.com/2/problems/dm-recipient-restricts-groups https://api.x.com/2/problems/dm-recipient-unavailable https://api.x.com/2/problems/dm-request-in-progress https://api.x.com/2/problems/dm-safety-limited https://api.x.com/2/problems/dm-safety-rejected https://api.x.com/2/problems/dm-sender-blocks-recipient https://api.x.com/2/problems/dm-sender-declined-dms https://api.x.com/2/problems/dm-sender-dms-closed https://api.x.com/2/problems/dm-sender-encrypted-unavailable https://api.x.com/2/problems/dm-sender-not-in-conversation https://api.x.com/2/problems/dm-sender-not-permitted https://api.x.com/2/problems/dm-sender-not-verified https://api.x.com/2/problems/dm-sender-phone-required https://api.x.com/2/problems/dm-sender-read-only https://api.x.com/2/problems/dm-sender-unavailable https://api.x.com/2/problems/dm-text-empty https://api.x.com/2/problems/dm-text-too-long https://api.x.com/2/problems/dm-too-few-participants https://api.x.com/2/problems/dm-too-many-participants https://api.x.com/2/problems/dm-unsupported-message discriminator mapping keys to the / response property for the response status

  • 23643fd75fe0Revision changes
    • breaking

      for the query request parameter max_results, default value was changed from 10 to 200

    • breaking

      added to the response body oneOf list for the response status

    • breaking

      added to the / response property oneOf list for the response status

    • info

      added the new optional query request parameter unread_only

    • info

      for the query request parameter max_results, the max was increased from 100.00 to 1000.00

    • info

      added the enum value active_follower_count to the property items/ of the query request parameter user.fields

    • info

      added the enum value admin_settings to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value group_description to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value group_description_key_version to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value invite to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value is_archived to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value last_read_event_id to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value newest_event_id to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value pending_member_ids to the property items/ of the query request parameter chat_conversation.fields

    • info

      added the enum value subscriber_count to the property items/ of the query request parameter user.fields

    • info

      added the enum value unread to the property items/ of the query request parameter chat_conversation.fields

    • info

      added https://api.twitter.com/2/problems/duplicate-rules https://api.twitter.com/2/problems/invalid-rules https://api.x.com/2/problems/recipient-not-messageable mapping keys to the response discriminator for the response status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added https://api.twitter.com/2/problems/duplicate-rules https://api.twitter.com/2/problems/invalid-rules https://api.x.com/2/problems/recipient-not-messageable discriminator mapping keys to the / response property for the response status