> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-d2bb4767.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Messages Lookup

> The Direct Messages lookup endpoints let you retrieve DM events for the authenticated user. Reference for the X API v2 standard tier covering lookup.

export const Button = ({href, children}) => {
  return <div className="not-prose">
    <a href={href}>
      <button className="x-btn">
        <span>{children}</span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

The Direct Messages lookup endpoints let you retrieve DM events for the authenticated user, including messages from both one-to-one and group conversations.

## Overview

<CardGroup cols={2}>
  <Card title="All DM events" icon="messages">
    Get all DM events for the user
  </Card>

  <Card title="One-to-one" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/5sylihPu5V0QjCj1/icons/xds/icon-chat.svg?fit=max&auto=format&n=5sylihPu5V0QjCj1&q=85&s=1105eda09b7d591dba971c27ca216a90" width="24" height="24" data-path="icons/xds/icon-chat.svg">
    Get events from a specific conversation
  </Card>

  <Card title="By conversation ID" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/5sylihPu5V0QjCj1/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=5sylihPu5V0QjCj1&q=85&s=38b56fbb17001c9ca7b5a9964772116a" width="24" height="24" data-path="icons/xds/icon-chat-unread.svg">
    Get events by conversation ID
  </Card>

  <Card title="Event types" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/zqrQWIG3W09H1y-k/icons/xds/icon-bell.svg?fit=max&auto=format&n=zqrQWIG3W09H1y-k&q=85&s=4f867f6e486fea5f6fc5b84e5c0c3e30" width="24" height="24" data-path="icons/xds/icon-bell.svg">
    Messages, joins, and leaves
  </Card>
</CardGroup>

***

## Endpoints

| Method | Endpoint                                                                                                            | Description                             |
| :----- | :------------------------------------------------------------------------------------------------------------------ | :-------------------------------------- |
| GET    | [`/2/dm_events`](/x-api/direct-messages/get-dm-events)                                                              | Get all DM events for the user          |
| GET    | [`/2/dm_conversations/with/:participant_id/dm_events`](/x-api/direct-messages/get-dm-events-for-a-dm-conversation)  | Get events from one-to-one conversation |
| GET    | [`/2/dm_conversations/:dm_conversation_id/dm_events`](/x-api/direct-messages/get-dm-events-for-a-dm-conversation-1) | Get events by conversation ID           |

***

## Event types

| Event               | Description                            |
| :------------------ | :------------------------------------- |
| `MessageCreate`     | A message was sent in the conversation |
| `ParticipantsJoin`  | A user joined the conversation         |
| `ParticipantsLeave` | A user left the conversation           |

***

## Data retention

<Note>
  Events from up to **30 days ago** are available through these endpoints.
</Note>

***

## Getting started

<Note>
  **Prerequisites**

  * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
  * A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
  * User Access Tokens via [3-legged OAuth](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow)
</Note>

<CardGroup cols={2}>
  <Card title="Quickstart" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/5Le46nzrFjzXflZ1/icons/xds/icon-rocket.svg?fit=max&auto=format&n=5Le46nzrFjzXflZ1&q=85&s=86832c7ce1dcc10b826f65f82953ce5e" href="/x-api/direct-messages/lookup/quickstart" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    Make your first DM lookup request
  </Card>

  <Card title="Integration guide" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/zqrQWIG3W09H1y-k/icons/xds/icon-book.svg?fit=max&auto=format&n=zqrQWIG3W09H1y-k&q=85&s=eaea7c09a0a0a8e555ac3ee081bb5e5f" href="/x-api/direct-messages/lookup/integrate" width="24" height="24" data-path="icons/xds/icon-book.svg">
    Key concepts and best practices
  </Card>

  <Card title="API Reference" icon="https://mintcdn.com/x-preview-mintlify-d2bb4767/5sylihPu5V0QjCj1/icons/xds/icon-code.svg?fit=max&auto=format&n=5sylihPu5V0QjCj1&q=85&s=c6e106dd65d5c5d5fc782a7853572cde" href="/x-api/direct-messages/get-dm-events" width="24" height="24" data-path="icons/xds/icon-code.svg">
    Full endpoint documentation
  </Card>

  <Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    Working code examples
  </Card>
</CardGroup>