> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-b8c19c78.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-b8c19c78/oeE9e4yE1fVC7B9c/icons/xds/icon-chat.svg?fit=max&auto=format&n=oeE9e4yE1fVC7B9c&q=85&s=97e4698b61e7e1479d506c33b17cb410" 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-b8c19c78/oeE9e4yE1fVC7B9c/icons/xds/icon-chat-unread.svg?fit=max&auto=format&n=oeE9e4yE1fVC7B9c&q=85&s=dc7efc350d5a801165f657988034c549" 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-b8c19c78/E26_WOQX_WsneS5z/icons/xds/icon-bell.svg?fit=max&auto=format&n=E26_WOQX_WsneS5z&q=85&s=8ea7307b20b304993a3996df8c1c9cad" 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-b8c19c78/dFhTI5o_cnAxhj8C/icons/xds/icon-rocket.svg?fit=max&auto=format&n=dFhTI5o_cnAxhj8C&q=85&s=3106e95425211d3b3a3bf22fdc4d994f" 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-b8c19c78/E26_WOQX_WsneS5z/icons/xds/icon-book.svg?fit=max&auto=format&n=E26_WOQX_WsneS5z&q=85&s=5c792c385b10a7b9a4cb673257c8d1f8" 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-b8c19c78/oeE9e4yE1fVC7B9c/icons/xds/icon-code.svg?fit=max&auto=format&n=oeE9e4yE1fVC7B9c&q=85&s=236739f51e6676fcc23005cc510ca3d5" 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>