> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-143107c1.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-143107c1/-vUZNvNnsedeyKnT/icons/xds/icon-chat.svg?fit=max&auto=format&n=-vUZNvNnsedeyKnT&q=85&s=65931703120a2ba61763b171daa57b14" 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-143107c1/-vUZNvNnsedeyKnT/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=-vUZNvNnsedeyKnT&q=85&s=c1e363f9c3637cf43d1ab592cd2e88c3" 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-143107c1/r6g1kiGndqT3mXyl/icons/xds/icon-bell.svg?fit=max&auto=format&n=r6g1kiGndqT3mXyl&q=85&s=6e43b79b6dc6df285276722136c94ce2" 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-143107c1/LjDupcgIJeQhUrTV/icons/xds/icon-rocket.svg?fit=max&auto=format&n=LjDupcgIJeQhUrTV&q=85&s=ab9d87f67ff2827df976c782467c9fe1" 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-143107c1/r6g1kiGndqT3mXyl/icons/xds/icon-book.svg?fit=max&auto=format&n=r6g1kiGndqT3mXyl&q=85&s=221001d25934bdf1f9d20077f943b9c8" 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-143107c1/-vUZNvNnsedeyKnT/icons/xds/icon-code.svg?fit=max&auto=format&n=-vUZNvNnsedeyKnT&q=85&s=1df744166b46c62535ed328bca70d1c0" 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>