Get DM history

1 credit per result returned · All plans from $0.00012/credit

Use this endpoint to sync participant-scoped DM pages before a support, CRM, warehouse, or agent workflow replies. Pass the connected participant account in account, store message IDs plus next_cursor, and keep full message text only in private systems.

Requires a connected X account passed via the account query parameter. DM history is participant-scoped, so pass the connected account that belongs to the conversation.

DM history responses can contain private message text. Store them in a private support, CRM, warehouse, or agent memory system. Do not write full DM bodies to shared logs or public artifacts.

Which DM workflow?

Read conversation history

Use GET /x/dm/{userId}/history with account, then store messages[].id and next_cursor in a private system.

Send text reply

Use POST /x/dm/{userId}, pass the same connected account, and store the returned messageId.

Send one media item

Use POST /x/media first, then pass the returned media ID as the only media_ids item on the DM send.

Resolve participant ID

Use GET /x/users/{id} when a workflow starts from a handle and needs the numeric userId for history or send calls.

curl -G https://xquik.com/api/v1/x/dm/44196397/history \
  --data-urlencode "account=your_handle" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

# Page 2
curl -G https://xquik.com/api/v1/x/dm/44196397/history \
  --data-urlencode "account=your_handle" \
  --data-urlencode "cursor=abc123" \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

The examples normalize each page into private dm_history rows. Store message_id, sender_id, receiver_id, message_text, created_at, optional media_url, conversation_user_id, sender_account, and page_next_cursor. Keep message_text only in private systems; use the IDs, timestamp, media URL, and job status in shared logs.

Path parameters

userId

string

required

Target X user ID for the DM conversation (numeric string).

Query parameters

account

string

required

X handle (without the @ prefix) of the connected X account used to read the conversation. DM history is participant-scoped, so the account must belong to the conversation. Connect an account on the dashboard before calling this endpoint.

cursor

string

Pagination cursor. Pass the next_cursor value from the previous response to fetch older messages.

maxId

string

Legacy pagination cursor. Use cursor for new integrations. When both are present, cursor takes precedence.

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Response

messages

object[]

Array of direct messages.

Show message object

string

Message ID.

text

string

Message text. Omitted if unavailable.

senderId

string

Sender user ID.

receiverId

string

Receiver user ID.

createdAt

string

ISO 8601 timestamp. Omitted if unavailable.

mediaUrl

string

URL of attached media (image, GIF, or video). Omitted when the message has no media attachment.

has_next_page

boolean

Whether older messages are available.

next_cursor

string

Opaque cursor for the next page. Empty string when no more messages.

{
  "messages": [
    {
      "id": "1893456789012345678",
      "text": "Hey, great tool!",
      "senderId": "44196397",
      "receiverId": "987654321",
      "createdAt": "2026-02-24T10:00:00.000Z"
    }
  ],
  "has_next_page": true,
  "next_cursor": "1893456789012345677"
}

{ "error": "invalid_user_id" }

The user ID is empty or invalid.

{ "error": "account_required", "message": "Provide ?account=<x_handle> for a connected X account. DM history requires a connected participant account." }

The account query parameter was missing or empty. Pass the handle of a connected X account that participates in the conversation.

{ "error": "unauthenticated" }

Missing or invalid API key.

{ "error": "no_subscription" }

No active subscription or insufficient credits. Possible error values: no_subscription, subscription_inactive, no_credits, insufficient_credits.

{ "error": "dm_not_permitted", "message": "X rejected the DM read. The connected account is not a participant in this conversation, or it needs reauthentication. Reconnect the account on the dashboard and try again." }

X rejected the DM read. The connected account is not a participant in this conversation, or it needs reauthentication. Reconnect the account and retry.

{ "error": "account_restricted" }

The connected X account is suspended, locked, or otherwise restricted. Use a different connected account.

{ "error": "account_needs_reauth" }

The connected account needs to be reauthenticated. Reconnect it from the dashboard.

{ "error": "account_not_found" }

The requested connected X account was not found. Connect it first or pass another account handle.

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

Your tier rate limit was exceeded. Wait for the Retry-After header before retrying.

{ "error": "x_api_unavailable" }

The normalized v1 response contract can return 424 when the read service is unavailable.

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

History sync handoff

Use this endpoint when a CRM, support desk, warehouse job, or agent needs participant-scoped DM context before sending a reply.

Dedupe imported messages

Store messages[].id as the external DM ID for CRM notes, support tickets, warehouse rows, or agent memory.

Preserve participants

Store messages[].senderId and messages[].receiverId with the connected account so each private conversation stays tied to the correct sender.

Resume older pages

Store next_cursor when has_next_page is true, then pass it as cursor on the next sync job.

Keep media context

Store optional messages[].mediaUrl with messages[].createdAt when a DM includes an image, GIF, or video attachment.

Related: Direct Message Workflow for lookup, participant-scoped history sync, messageId storage, and media handoff; Get User to resolve the recipient userId; Send DM to reply from the connected account; Upload Media when a reply needs one uploaded mediaId.

Documentation Index

​Which DM workflow?

Read conversation history

Send text reply

Send one media item

Resolve participant ID

​Path parameters

​Query parameters

​Headers

​Response

​History sync handoff

Dedupe imported messages

Preserve participants

Resume older pages

Keep media context

Which DM workflow?

Path parameters

Query parameters

Headers

Response

History sync handoff