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).

Search parameter constraints

  • You can use either cursor OR filter parameters (sender, receiver, sourceChainSelector, destChainSelector, readyForManualExecOnly, sourceTransactionHash, sourceTokenAddress, q), but NOT both simultaneously.
  • limit can always be specified regardless of whether you're using cursor or filters.
  • Violating constraints will return a 400 Bad Request.

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
  • Invalid (400): /messages?sender=0x123...&cursor=WyJuYXR1cmFsIiwxMjM0NV0=

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