Get Twitter DMs API

List Twitter DM conversations and messages via API across the All, Requests, and Hidden inboxes. $0.002 per call, ~50 per page. GetXAPI DM list endpoint docs.

POST/twitter/dm/list

This endpoint costs $0.002 per API call and returns ~50 conversations/messages per page.

Lists the auth_token holder's DM inbox — conversations plus their recent messages — across the three inbox tabs. Page through next_cursor to retrieve the entire inbox.

Request Body

Field	Type	Required	Description
`auth_token`	string	Yes	User's auth token
`ct0`	string	No	Optional current CSRF token cookie. When provided with `twid`, skips server-side credential resolution.
`twid`	string	No	Optional current user ID cookie, for example `u=1234567890`. Must be provided with `ct0`.
`tab`	string	No	Inbox to read: `all` (default — your main inbox), `requests` (message requests), `hidden` (low-quality / spam)
`cursor`	string	No	Pagination cursor (`next_cursor`) from a previous response. Pages within the same `tab`
`count`	number	No	Page size (default 50)
`proxy`	string	No	Proxy URL (`http://`, `https://`, `socks5://`, or `socks4://`)

Notes

If you already have current ct0 and twid, send both to skip the extra server-side credential bootstrap from auth_token. If either one is omitted, the server resolves them from auth_token as before. Stale or invalid supplied values are not validated upfront and may fail on the actual Twitter action instead of returning an early 401.
The first page (no cursor) returns the most recent conversations for the tab. Keep calling with next_cursor until has_more is false to retrieve the whole inbox.
conversations groups messages by thread (full participant profiles + last-message preview + read/unread state); messages is the flat list of message events in the page; events are non-message conversation events (request accepted, encryption enabled, etc.); users is a lookup of every referenced user.
To read one conversation's full history, use DM Conversation.

Conversation: conversation_id, type (ONE_TO_ONE | GROUP_DM), name + avatar_url (group DMs), trusted, low_quality, muted, nsfw, read_only, notifications_disabled, unread, last_read_event_id, sort_timestamp, participants[], last_message.

Participant / user: id, screen_name, name, description, profile_image_url, followers_count, friends_count, verified, is_blue_verified, protected.

Message: id, conversationId, createdAt, senderId, recipientId, text, media (photo/video/animated_gif — url, width, height, plus video_url + duration_ms for video), shared_tweet (a quoted tweet's id/url/text/author), card (link preview), links[], reactions[], reply_to_message_id, edit_count.

Response (200)

{
  "userId": "1345154135381794816",
  "tab": "all",
  "conversation_count": 14,
  "message_count": 99,
  "has_more": true,
  "next_cursor": "1928684596763250690",
  "conversations": [
    {
      "conversation_id": "3012852462-1345154135381794816",
      "type": "ONE_TO_ONE",
      "name": null,
      "avatar_url": null,
      "trusted": true,
      "low_quality": false,
      "muted": false,
      "nsfw": false,
      "read_only": false,
      "notifications_disabled": false,
      "unread": false,
      "last_read_event_id": "2059239475419779072",
      "sort_timestamp": "2026-05-26T10:11:00.000Z",
      "participants": [
        {
          "id": "3012852462",
          "screen_name": "someuser",
          "name": "Some User",
          "profile_image_url": "https://pbs.twimg.com/...",
          "followers_count": 1200,
          "verified": false,
          "is_blue_verified": true,
          "protected": false
        }
      ],
      "last_message": {
        "id": "2059239475419779072",
        "text": "see you then",
        "senderId": "3012852462",
        "createdAt": "2026-05-26T10:11:00.000Z"
      }
    }
  ],
  "messages": [
    {
      "id": "2059239475419779072",
      "conversationId": "3012852462-1345154135381794816",
      "createdAt": "2026-05-26T10:11:00.000Z",
      "senderId": "3012852462",
      "recipientId": "1345154135381794816",
      "text": "check this out",
      "media": {
        "type": "photo",
        "url": "https://pbs.twimg.com/dm/.../photo.jpg",
        "width": 1200,
        "height": 800
      },
      "shared_tweet": null,
      "card": null,
      "links": [],
      "reactions": [],
      "reply_to_message_id": null,
      "edit_count": 0
    }
  ],
  "events": [
    {
      "type": "trust_conversation",
      "conversationId": "1345154135381794816-1516927548352917504",
      "createdAt": "2026-03-01T09:00:00.000Z",
      "reason": "accept"
    }
  ],
  "users": {
    "3012852462": {
      "id": "3012852462",
      "screen_name": "someuser",
      "name": "Some User",
      "profile_image_url": "https://pbs.twimg.com/...",
      "followers_count": 1200,
      "verified": false,
      "is_blue_verified": true,
      "protected": false
    }
  }
}

Error Responses

400 - Invalid tab

{
  "error": "Invalid tab \"foo\". Allowed: all (inbox), requests (message requests), hidden (low-quality/spam)."
}

401 - Invalid auth_token

{
  "error": "Invalid auth_token - could not extract userId"
}

Examples

# Main inbox
curl -X POST "https://api.getxapi.com/twitter/dm/list" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "your_auth_token" }'

# Message requests, next page
curl -X POST "https://api.getxapi.com/twitter/dm/list" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_token": "your_auth_token",
    "tab": "requests",
    "cursor": "1928684596763250690",
    "count": 50
  }'

# Hidden / spam requests
curl -X POST "https://api.getxapi.com/twitter/dm/list" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "your_auth_token", "tab": "hidden" }'

DM List