> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-b90e1c4d.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-b90e1c4d/HEs9RRCCIaKc_EuF/icons/xds/icon-chat.svg?fit=max&auto=format&n=HEs9RRCCIaKc_EuF&q=85&s=f00c7948dcb8c0f19c1bdfd4f1cd47f7" 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-b90e1c4d/HEs9RRCCIaKc_EuF/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=HEs9RRCCIaKc_EuF&q=85&s=c3d1676d19f5ef7add0ef8eb3f542b34" 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-b90e1c4d/FzxSSaEcmuIUnJHr/icons/xds/icon-bell.svg?fit=max&auto=format&n=FzxSSaEcmuIUnJHr&q=85&s=f45e89d127f95695b01bc46915839c60" 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-b90e1c4d/azCBEsesh7C8Sy1b/icons/xds/icon-rocket.svg?fit=max&auto=format&n=azCBEsesh7C8Sy1b&q=85&s=875b30c0ff514c2a738094c97fb79bc4" 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-b90e1c4d/FzxSSaEcmuIUnJHr/icons/xds/icon-book.svg?fit=max&auto=format&n=FzxSSaEcmuIUnJHr&q=85&s=53c80edab12a4d2023f5bf925c9049dd" 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-b90e1c4d/HEs9RRCCIaKc_EuF/icons/xds/icon-code.svg?fit=max&auto=format&n=HEs9RRCCIaKc_EuF&q=85&s=8a18cd907c79967a27fee26193a7e244" 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>