> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-20b812f3.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-20b812f3/w_10n4coWevK199E/icons/xds/icon-chat.svg?fit=max&auto=format&n=w_10n4coWevK199E&q=85&s=bc8715f5912ad6d72c214cd48a3a1fac" 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-20b812f3/w_10n4coWevK199E/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=w_10n4coWevK199E&q=85&s=92da5b62b6349db32800e684d019a4a0" 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-20b812f3/qtPNqZK8azZzDyc_/icons/xds/icon-bell.svg?fit=max&auto=format&n=qtPNqZK8azZzDyc_&q=85&s=c1d902115c7537cbd31cee58327a299d" 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-20b812f3/-FYSR9qrbg6jvg5i/icons/xds/icon-rocket.svg?fit=max&auto=format&n=-FYSR9qrbg6jvg5i&q=85&s=b57dd961032da75535651d85f6e058e4" 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-20b812f3/qtPNqZK8azZzDyc_/icons/xds/icon-book.svg?fit=max&auto=format&n=qtPNqZK8azZzDyc_&q=85&s=05aa323f8265eabe1f13a16fbac12fb7" 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-20b812f3/w_10n4coWevK199E/icons/xds/icon-code.svg?fit=max&auto=format&n=w_10n4coWevK199E&q=85&s=24c1c2ab976ed540089af370c804244e" 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>