Skip to main content
GET https://xquik.com/api/v1/x/dm/{userId}/history
1 credit per result returned · All plans from $0.00012/credit
This route reads the DM history between a connected account and one user. Pass the connected account through account. Store message IDs and next_cursor in private systems. Keep full message text private. Use Send DM when the workflow needs a reply. Compare fields with X’s Direct Messages lookup guide. Xquik returns the normalized message fields listed below.
Requires a connected X account passed via the account query parameter. Only a participant can read a conversation. Pass the connected account that belongs to it.
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 in the DM.

Resolve participant ID

Use GET /x/users/{id} when a workflow starts from a handle and needs the numeric userId. History or send calls use it.
These examples turn each page into private dm_history rows. Store message_id, sender_id, receiver_id, message_text, and created_at. Also store optional media_url, conversation_user_id, sender_account, and page_next_cursor for each page. Keep message_text only in private systems. Use IDs, timestamps, media URLs, and job status in shared logs.

Path parameters

Query parameters

Headers

Response

200 OK

400 Invalid user ID

The user ID is empty or invalid.

400 Account required

{ "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.

401 Unauthenticated

Supply a valid API key or OAuth bearer token.

402 Insufficient credits

Metered access requires enough available credits. Possible error values include no_subscription, subscription_inactive, no_credits, and insufficient_credits.

403 DM not permitted

{ "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. Use a participating connected account. If it needs reauthentication, reconnect it before retrying.

403 Account restricted

{ "error": "account_restricted" } The connected X account is suspended, locked, or otherwise restricted. Use a different connected account.

403 Account needs reauth

{ "error": "account_needs_reauth" } Reconnect the connected account from the dashboard.

404 Account not found

Xquik did not find the requested connected X account. Connect it first or pass another account handle.

429 Rate limit exceeded

You exceeded your tier’s rate limit. Wait for Retry-After before retrying.

424 Dependency failed

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

502 X API unavailable

The read service failed. Retry after a short delay.

Twitter DM API questions

Can I retrieve DM history?

Yes. Call GET /x/dm/{userId}/history with a participating connected account.

Can I send a reply through this endpoint?

No. Use Send DM. This endpoint reads history only.

Does this endpoint create direct message webhooks?

No. It reads participant-scoped history when called. It does not register webhooks.

How do I authenticate?

Send an API key or OAuth bearer token.

How do I handle a rate limit?

Wait for Retry-After, then retry the same page.

History sync handoff

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

Deduplicate imported messages

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

Keep participants

Store messages[].senderId and messages[].receiverId with the connected account. Do this 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 for a DM image, GIF, or video attachment.
Related. Direct Message Workflow covers lookup, participant-scoped history sync, messageId storage, and media handoff. Get User resolves the recipient userId. Send DM replies from the connected account. Use Upload Media when a reply needs one uploaded mediaId.

Response examples

  • 400 { "error": "invalid_user_id" }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 404 { "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." }
  • 424 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 503 { "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }