For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SDKsHelp CenterLog inSign up
    • Overview
  • Getting Started
    • API Mechanics
    • Quickstart
  • Guides
    • Communications API
    • Troubleshooting
    • Events
    • Changelog
  • Comms API Reference
      • Summary
      • POSTSend Messages
      • GETList Messages
      • GETFetch a Message
      • GETFetch a Message Operation
      • GETList Message Operations
      • GETSeek a Message by an Identifier
LogoLogo
SDKsHelp CenterLog inSign up
Comms API ReferenceMessages

List Messages

GET
https://comms.twilio.com/v1/Messages
GET
/v1/Messages
1import { TwilioClient } from "twilio-comms";
2
3async function main() {
4    const client = new TwilioClient({
5        accountId: "YOUR_ACCOUNTID_HERE",
6        authToken: "YOUR_AUTHTOKEN_HERE",
7    });
8    await client.messages.list({});
9}
10main();
1{
2  "messages": [
3    {
4      "createdAt": "2023-08-24T14:15:22Z",
5      "from": {
6        "address": "+12065558844",
7        "channel": "SMS",
8        "senderId": "comms_sender_01h9krwprkeee8fzqspvwy6nq8",
9        "senderPoolId": "comms_senderpool_01h9krwprkeee8fzqspvwy6nq8"
10      },
11      "id": "comms_message_01h2xcejqtf2nbrexx3vqjhp41",
12      "related": [
13        {
14          "name": "OPERATION",
15          "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
16          "uri": "https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h2xcejqtf2nbrexx3vqjhp41"
17        }
18      ],
19      "scheduledFor": null,
20      "status": "SENT",
21      "tags": {},
22      "to": [
23        {
24          "address": "+14153901002",
25          "channel": "PHONE",
26          "profileId": "mem_profile_01h9krwprkeee8fzqspvwy6nq7",
27          "memoryStoreId": "mem_store_00000000000000000000000000"
28        }
29      ],
30      "updatedAt": "2023-08-24T14:15:22Z",
31      "deletedAt": null
32    },
33    {
34      "createdAt": "2023-08-24T14:15:22Z",
35      "from": {
36        "address": "+12065558844",
37        "channel": "WHATSAPP",
38        "senderId": "comms_sender_01h9krwprkeee8fzqspvwy6nq8"
39      },
40      "id": "comms_message_01h2xcejqtf2nbrexx3vqjhp41",
41      "related": [
42        {
43          "name": "OPERATION",
44          "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
45          "uri": "https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h2xcejqtf2nbrexx3vqjhp41"
46        }
47      ],
48      "scheduledFor": null,
49      "status": "SENT",
50      "tags": {},
51      "to": [
52        {
53          "address": "+14153901002",
54          "channel": "PHONE",
55          "profileId": "mem_profile_01h9krwprkeee8fzqspvwy6nq7",
56          "memoryStoreId": "mem_store_00000000000000000000000000"
57        }
58      ],
59      "updatedAt": "2023-08-24T14:15:22Z",
60      "deletedAt": null
61    }
62  ],
63  "pagination": {
64    "next": null,
65    "self": "eyJTSyI6IkEjMDFqbmVoYm5xYWZmNDlrazUxZHA1bmN5bXciLCJTSzEiOiJBI2FjdGl2YXRlZCMyMDI1LTAzLTAzVDE3OjM3OjQ3WiMwMWpuZWhibnFhZmY0OWtrNTFkcDVuY3ltdyIsIlBLIjoiQyNBQzYwMzg4ODJiZDY5ZWIyNGM4YzU4ZGI5NjE4NjE3OTE4I0EifQ=="
66  }
67}

This operation fetches a paginated list of Messages.

Data retention: Records are available for 7 days after creation. Requests for data older than 7 days may return incomplete results.

Was this page helpful?
Previous

Fetch a Message

Next
Built with

Authentication

AuthorizationBasic

Basic authentication of the form Basic <account_id:auth_token>.

OR
AuthorizationBasic

Basic authentication of the form Basic <api_key:api_key_secret>.

Query parameters

operationIdstringOptionalformat: "^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}"
Filter Messages by Operation ID.
sessionIdstringOptionalformat: "^comms_session_[a-hjkmnpqrstv-z0-9]{26,34}"
Filter Messages by Session ID.
startDatestringOptionalformat: "date-time"

Filter to Messages created after the specified date and time in ISO 8601 format. The date is in RFC3339 format. (e.g., 2025-06-18T12:00:00Z)

endDatestringOptionalformat: "date-time"

Filter to Messages created before the specified date and time in ISO 8601 format. The date is in RFC3339 format and must be greater than startDate if provided. (e.g., 2025-06-18T12:00:00Z)

profilestringOptionalformat: "^mem_profile_[0-7][a-hjkmnpqrstv-z0-9]{25,34}"
Filter Messages sent or received by Profile ID.
channelenumOptional
Filter Messages by channel.
Allowed values:
statusenumOptional
Filter Messages by Delivery Status.
tagsstringOptionalformat: "^(?:[a-zA-Z0-9._~-]+:[a-zA-Z0-9._~-]+;){1,10}$"

Match messages by one or many tags. If more than one tag is specified in the query, the search will return messages that have all the tags. For Example: GET /Messages?tags=region:EMEA;campaign:BUY_STUFF;

pageTokenstringOptional
The token to retrieve the next page of results.
pageSizeintegerOptional1-1000Defaults to 50
The number of resources to return in a page.

Response

OK
messageslist of objects
A list of Messages.
paginationobject

Metadata for paginated results. This object contains two tokens to navigate through paginated results.

  • Use next to retrieve the ‘next’ page in the result list.
  • Use self to retrieve the same page of the result list again.
  • Supply the token in the pageToken query param.

Errors

400
Bad Request Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error