DM Conversation API

GET dm/conversation returns the full message history of one direct-message conversation on X (Twitter), given a conversation_id obtained from GET /dm/list. The response includes the conversation_id, a count of messages returned, and a messages array where each entry has an id, timestamp, sender_id, and text. It is read-only and does not send messages.

curl -X GET "https://example.com/dm/conversation?conversation_id=1749154312754794496-1972455697997824000"

{  "conversation_id": "1749154312754794496-1972455697997824000",  "count": 1,  "messages": [    {      "id": "1988752174906749349",      "time": "1762990442000",      "sender_id": "1972455697997824000",      "text": "This isnt my main, chat to me here @baywilliams_12"    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use this endpoint to pull the full message history inside one specific DM thread once you already have its conversation_id from GET /dm/list. Reach for it when you need message-level detail (text, sender, timestamp) rather than just the list of conversations itself.

Notes

• Needs a session for the account you are reading: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
• time is a string of epoch milliseconds; divide by 1000 for Unix seconds.
• Read-only: reads messages; it does not send DMs.

Related endpoints

• Send DM: Send a direct message from your authenticated account.
• DM Inbox: List the Direct Message conversations for your registered account.

FAQ

Where do I get the conversation_id for this call?

Call GET /dm/list first. Each conversation entry it returns includes a conversation_id, which you then pass as the required parameter to GET dm/conversation. There is no way to derive a conversation_id from a user ID directly through this endpoint.

How much does one call to this endpoint cost, and does the cost scale with message count?

Each call to GET dm/conversation costs 0.0016 credits, a flat per-request cost regardless of how many messages are in the conversation. The response's count field tells you how many messages were returned so you can track volume without the cost varying per message.