GET https://xquik.com/api/v1/x/dm/{userId}/history
1 credit per result returned · All plans from $0.00012/credit
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.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 includeno_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 forRetry-After before retrying.424 Dependency failed
The opt-in normalized contract returns 424 when the read service fails. Sendxquik-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. CallGET /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 forRetry-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." }