---
title: "Pagination and filtering"
description: "Page through any list with cursors, filter it with one field[operator]=value grammar, and sort or search it. There is no catch-all filter parameter to guess."
canonical_url: "https://twominutebilling.com/help/developers/api-essentials/pagination-and-filtering"
---
# Pagination and filtering

> Page through any list with cursors, filter it with one field[operator]=value grammar, and sort or search it. There is no catch-all filter parameter to guess.

Lists that grow with your customer volume page with cursors, and you filter them with one `field[operator]=value` grammar. Code that pages and filters one list works for the others.

## Read a list response

Every list that grows with your customer volume is cursor-paginated and returns the same shape:

```json
{
  "object": "list",
  "data": [ … ],
  "has_more": true,
  "next_cursor": "k:inv_9f2c…",
  "total": 1284
}
```

## Page through a list

Pass `next_cursor` back as `starting_after`:

```bash
curl "$TMBILLING_URL/v1/businesses/$BIZ/invoices?limit=50" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"

curl "$TMBILLING_URL/v1/businesses/$BIZ/invoices?limit=50&starting_after=k:inv_9f2c…" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

`limit` defaults to 50 and caps at 1000. Treat `next_cursor` as opaque — it encodes how tmbilling
is walking the current sort, so parsing it breaks when the sort changes.

<tip title="Stop on has_more, not on a short page">

`has_more: false` means the end of the list. A page can be shorter than `limit` and still not be
the last one.

</tip>

## Filter a list

Write filters as `field[operator]=value`:

```http
?created_at[after]=2026-09-01&status[in]=paid,posted
```

There is no generic `filters` parameter. Each filterable field is its own documented query
parameter, and any query key that is neither a filter nor a documented parameter returns `400`.
So a misspelled filter tells you, rather than quietly returning an unfiltered list.

### Select an operator

<table>
<thead>
  <tr>
    <th>
      Field type
    </th>
    
    <th>
      Operators
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Text
    </td>
    
    <td>
      <code>
        is
      </code>
      
      , <code>
        is_not
      </code>
      
      , <code>
        contains
      </code>
      
      , <code>
        not_contains
      </code>
      
      , <code>
        starts_with
      </code>
      
      , <code>
        ends_with
      </code>
      
      , <code>
        is_present
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Enum
    </td>
    
    <td>
      <code>
        is
      </code>
      
      , <code>
        is_not
      </code>
      
      , <code>
        in
      </code>
      
      , <code>
        not_in
      </code>
      
      , <code>
        is_present
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Boolean
    </td>
    
    <td>
      <code>
        is
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Number
    </td>
    
    <td>
      <code>
        is
      </code>
      
      , <code>
        is_not
      </code>
      
      , <code>
        gt
      </code>
      
      , <code>
        gte
      </code>
      
      , <code>
        lt
      </code>
      
      , <code>
        lte
      </code>
      
      , <code>
        between
      </code>
      
      , <code>
        is_present
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Date
    </td>
    
    <td>
      <code>
        on
      </code>
      
      , <code>
        before
      </code>
      
      , <code>
        after
      </code>
      
      , <code>
        between
      </code>
      
      , <code>
        in_last
      </code>
      
      , <code>
        in_next
      </code>
      
      , <code>
        is_present
      </code>
    </td>
  </tr>
</tbody>
</table>

Most operators take one scalar. Four take something else:

<table>
<thead>
  <tr>
    <th>
      Operator
    </th>
    
    <th>
      Value
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        in
      </code>
      
      , <code>
        not_in
      </code>
    </td>
    
    <td>
      a comma-separated set
    </td>
    
    <td>
      <code>
        status[in]=paid,posted
      </code>
      
       matches any member
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        between
      </code>
    </td>
    
    <td>
      exactly two values
    </td>
    
    <td>
      <code>
        total[between]=1000,5000
      </code>
      
      , both ends inclusive
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        in_last
      </code>
      
      , <code>
        in_next
      </code>
    </td>
    
    <td>
      a number of <strong>
        days
      </strong>
    </td>
    
    <td>
      <code>
        created_at[in_last]=30
      </code>
      
       — days, not hours, not an ISO duration
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        is_present
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       or <code>
        false
      </code>
    </td>
    
    <td>
      <code>
        po_number[is_present]=false
      </code>
      
       asks whether the field is set
    </td>
  </tr>
</tbody>
</table>

Give dates in ISO-8601. tmbilling resolves day boundaries in the **business's** timezone rather
than UTC, so `created_at[on]=2026-09-01` means that calendar day where the business is — the same
day the row is labelled with everywhere else.

## Sort a list

```http
?sort_by[desc]=created_at
?sort_by[asc]=total
```

Sort on one field at a time. tmbilling returns newest first by default.

## Search a list

Lists that support it take `q=<text>` and search the fields a person would search by, such as a
customer's name and email or an invoice number. Combine it with filters:

```bash
curl "$TMBILLING_URL/v1/businesses/$BIZ/customers?q=ada&status[is]=active&limit=20" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

## Related

- [API reference](https://twominutebilling.com/help/developers/api-reference)


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.