> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ordering results
> Sort list results deterministically with the order_by parameter.
Every list endpoint accepts an `order_by` parameter that controls how results are ordered. The detailed syntax lives in the [Pagination reference](/api-reference/conventions/pagination#order-by); this page covers the mental model and recommended patterns.
## The mental model
`order_by` is a **comma-separated list of ordering expressions**, applied left-to-right:
```
order_by=createdAt desc, status, name
```
This means: order by `createdAt` descending; ties broken by `status` ascending; ties on `(createdAt, status)` broken by `name` ascending.
The server appends an internal tie-breaker (typically the resource id) so pagination is fully deterministic — you should not rely on the tie-breaker's existence, name, or direction.
## Direction
| Suffix | Direction |
| -------- | ------------------- |
| *(none)* | Ascending (default) |
| ` desc` | Descending |
```
order_by=createdAt # ascending
order_by=createdAt desc # descending
```
`asc` is also accepted as an explicit suffix but is the default — omit it for terseness.
## Which fields can you order by?
Ordering fields are **explicitly allowlisted by each endpoint**. The most common allowed field is `createdAt`, which is what you want for nearly every "newest first" use case.
For the canonical list of orderable fields per endpoint, consult that endpoint's reference page. Using an unknown field returns `INVALID_ORDER_BY` (HTTP 400).
## Patterns you will use
### Newest first
```
order_by=createdAt desc
```
This is the workhorse — what you want for transaction lists, log views, dashboards. Stable, intuitive, and supported by every list endpoint.
### Oldest first (replay order)
```
order_by=createdAt
```
Use this when you are processing historical data in the order it was created — reconciliation jobs, event sourcing, audit playback.
### Multiple criteria
```
order_by=status, createdAt desc
```
Group items by `status`, then within each group show newest first. Useful for prioritized inboxes (e.g., show `AWAITING_APPROVAL` before `SUCCESS`).
The ordering is **lexicographic** across the criteria, not "primary then secondary." If two items have the same `status`, the second criterion (`createdAt desc`) breaks the tie. If they have different statuses, `status` alone determines order.
## Ordering and pagination must agree
When you paginate (`page_token`), the `order_by` you used on the first call **must stay identical** for every subsequent page. Changing it returns `INVALID_PAGE_TOKEN`.
Practical rule: pick your ordering **before** you start the iteration, hold it constant for the duration, and re-iterate from the beginning if you need a different ordering.
## When ordering matters for consistency
| Use case | Ordering recommendation |
| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Reconciliation that processes orders in creation order | `createdAt` ascending (oldest first) |
| Showing the user "what just happened" | `createdAt desc` (newest first) |
| Resuming an interrupted job from a known cursor | Whatever ordering the cursor was built with — do not switch mid-iteration |
| One-time analytical query | Anything — but tie-break with a unique field if you sort the results downstream |
## What ordering does NOT do
* It does **not** filter. Use `filter` for that.
* It does **not** affect counts or totals.
* It does **not** change result set membership — only sequence.
Ordering is purely about sequence within a fixed result set defined by `filter`.
## Reference
Syntax, field restrictions, errors.