Skip to main content
Version: v2

Retrieve multiple messages with filtering

GET 
/messages

Search and filter CCIP messages with cursor-based pagination. Results are ordered by send time (most recent first).

Use Cases:

  • Filter by sender or receiver address
  • Filter by source or destination chain
  • Filter by messages ready for manual execution only
  • Filter by source (send) transaction hash
  • Filter by source token address
  • General identifier search (q) — matches across several fields tied to a message (e.g. sender/receiver addresses, send/commit/receipt-related transaction hashes, message ID, token addresses etc.).

q vs named query parameters

  • Use sender / receiver when results must be strictly from or to that address.
  • Use sourceTransactionHash when the value is specifically the source send transaction hash.
  • Use sourceTokenAddress when filtering by a token that appears in transfers.
  • Use q for a single “paste an identifier” search, or when you are unsure which specific field holds the value, or when you have an address and want to find all messages it's involved in (as sender, receiver, token party, etc.).

q with other filters
q can be combined with other filters (for example q=0xabc...&sourceChainSelector=...).

Search behavior note
Because q spans several fields, a result may match the value in a different role than you expect (for example an address appearing as a token party rather than as sender).

Pagination and filters

  • limit can always be specified.
  • Filter parameters may be sent with a cursor as long as each provided filter matches the filters encoded in that cursor. Omitted filters are allowed and do not override the cursor.
  • To change filters, start a new search without a cursor.
  • Sending a filter value that differs from the cursor returns 400 with message: "The filter conflicts with the cursor. To search with different filters, start a new search without a cursor."

Total match count (totalCount, isCountCapped)

  • totalCount represents the total number of messages matching the search filters.
  • When isCountCapped is false, totalCount is the exact number of matching messages.
  • When isCountCapped is true, the search matches more than totalCount results.

Usage examples

  • Filtered search: /messages?sender=0x123...&limit=50
  • General search: /messages?q=0xabc...,0xdef...&sourceChainSelector=...&limit=50
  • Next page: /messages?cursor=WyJuYXR1cmFsIiwxMjM0NV0=&limit=20
  • Next page with matching filters: /messages?cursor=...&sender=0x123...&limit=20 (sender must match initial cursor filters or can be omitted)
  • Invalid (400): /messages?cursor=...&sender=0xOTHER... (sender differs from cursor)

Request​

Responses​

The request was successful. Returns an array of MessageSearchResult objects with pagination metadata.

Response Headers
    X-Request-ID

    Unique request identifier for debugging and support