> ## Documentation Index
> Fetch the complete documentation index at: https://developers.staging01.melio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Melio list endpoints are cursor-paginated and return results newest-first. Learn how to page through results, apply filters, and use metadata matching.

All list endpoints return results in reverse chronological order - newest `createdAt` first - and use cursor-based pagination. Unlike offset pagination, cursor pagination stays stable as new records are created between requests: you never see duplicates or skip items mid-page.

## Response envelope

Every list response wraps its results in the following shape:

```json theme={null}
{
  "data": [ /* resource objects */ ],
  "hasMore": true
}
```

* **`data`** - the array of resource objects for the current page.
* **`hasMore`** - `true` if there are more records beyond this page; `false` when you have reached the end.

## Pagination parameters

Control page size and position with these query parameters:

| Parameter            | Description                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `limit`              | Number of results to return. Accepts `1`-`50`. Defaults to `50`.                                              |
| `startingAfter=<id>` | Return the page of results that comes **after** the given resource ID, moving forward through older records.  |
| `endingBefore=<id>`  | Return the page of results that comes **before** the given resource ID, moving backward toward newer records. |

`startingAfter` and `endingBefore` are mutually exclusive. Supplying both in the same request returns a `400 Bad Request`.

## Walking forward through pages

To iterate through all records, start with your desired `limit`, check `hasMore`, and use the last item's ID as `startingAfter` on the next request. Repeat until `hasMore` is `false`.

```http theme={null}
### Page 1 - first request, no cursor
GET /v2/payments?limit=25 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: data[24].id = "pay_last_on_page_1", hasMore = true

### Page 2 - pass the last ID from page 1
GET /v2/payments?limit=25&startingAfter=pay_last_on_page_1 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: data[24].id = "pay_last_on_page_2", hasMore = true

### Page 3 - pass the last ID from page 2
GET /v2/payments?limit=25&startingAfter=pay_last_on_page_2 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL

### Response: hasMore = false - you have reached the last page
```

## Filtering

Each list endpoint exposes its own filter parameters. The following filters are available across most endpoints:

| Parameter             | Description                                                                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalId`          | Look up resources by your own identifier instead of the Melio-assigned ID.                                                                          |
| `created[gte]`        | Return only records created at or after this RFC 3339 date-time (e.g., `2024-01-01T00:00:00Z`).                                                     |
| `created[lte]`        | Return only records created at or before this RFC 3339 date-time.                                                                                   |
| `metadata[key]=value` | Match resources where the given metadata key equals the given value. Supply multiple `metadata[key]` parameters to require all of them (AND logic). |

The payments list endpoint also supports these additional filters:

| Parameter              | Description                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------- |
| `status`               | Filter by payment status: `scheduled`, `in-progress`, `completed`, `failed`, or `canceled`. |
| `originatingAccountId` | Return only payments funded from this internal account ID.                                  |
| `receivingAccountId`   | Return only payments delivered to this external account ID.                                 |

**Example - find all completed payments for an invoice:**

```http theme={null}
GET /v2/payments?status=completed&metadata[invoiceId]=INV-00123 HTTP/1.1
Host: api.melio.com
api-key: YOUR_API_KEY
Melio-Entity-Id: ent_4kQz9mXpR2wL
```

## Sorting

The sort order is fixed: results always come back newest-first by `createdAt`. There is no `sortBy` parameter.

<Note>
  All filters combine with AND logic - every filter you supply must match for a record to appear. Filters also compose cleanly with pagination: once you have a filtered result set, use `startingAfter` and `endingBefore` exactly as you would on an unfiltered list to walk through its pages.
</Note>