{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-api-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Filtering, sorting and pagination"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"filtering-sorting-and-pagination","__idx":0},"children":["Filtering, sorting and pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints across the API share a common set of query parameters. The exact"," ","parameters accepted by any given endpoint are documented on that endpoint — this"," ","page explains what they mean and how they interact."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":1},"children":["Pagination"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page number to retrieve. Send it to page the results at all — see below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Records per page. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]},", capped at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]},". Only applies when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," is sent."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Asking for more than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]}," records per page is not an error — you get ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pagination is opt-in."]}," A list request that does not carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," returns"," ","every matching record as a bare JSON array, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]}," is ignored. Send"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and the response becomes a pagination envelope instead:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"current_page\": 1,\n  \"per_page\": 10,\n  \"from\": 1,\n  \"to\": 10,\n  \"data\": [ ... ],\n  \"path\": \"https://example.rosterfy.com/api/v2/event\",\n  \"first_page_url\": \"https://example.rosterfy.com/api/v2/event?page=1\",\n  \"prev_page_url\": null,\n  \"next_page_url\": \"https://example.rosterfy.com/api/v2/event?page=2\",\n  \"current_page_url\": \"https://example.rosterfy.com/api/v2/event?page=1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no total count and no last-page number: keep requesting pages until"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next_page_url"]}," comes back ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," carries an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}," key with the record's fields and a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions"]}," key describing what the authenticated caller may do with it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Listings are scoped to what your token may read, silently."]}," A record your"," ","token is not entitled to see is simply absent — the list is shorter, and nothing"," ","in the response says anything was left out. So a count taken from a listing is a"," ","count of what you may read, not of what exists, and two tokens on the same"," ","account can legitimately get different totals from the same request. Where a"," ","single record would answer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}," (see ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Errors and status codes"]},"), a listing"," ","just omits it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sorting","__idx":2},"children":["Sorting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_by"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Attribute to sort on."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_order"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asc"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sortable attributes vary per resource; the endpoint's own documentation lists"," ","which are supported."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"filtering","__idx":3},"children":["Filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter"]}," accepts an array of conditions. The filterable attributes differ per"," ","resource and are listed on each endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"expanding-related-data","__idx":4},"children":["Expanding related data"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["with"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include related resources in the response. Relations are not returned unless requested."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["extras"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Include computed or derived values that are not stored fields."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requesting relations you don't need costs response time on both sides — ask for"," ","the narrowest set that satisfies your use case."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"localisation","__idx":5},"children":["Localisation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_locale"]}," returns translatable content in a specific language, e.g."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["?_locale=en-US"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A request returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one"]}," locale. If your application needs the same records in"," ","several languages, make one request per locale and merge client-side. Values"," ","that have no translation for the requested locale fall back to the account's"," ","default language rather than returning empty."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"soft-deleted-records","__idx":6},"children":["Soft-deleted records"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some resources are soft-deleted: the record remains retrievable after deletion."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["By default, deleted records are excluded from responses."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Effect"},"children":["Effect"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["with_deleted=1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return active ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["and"]}," deleted records."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["only_deleted=1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only"]}," deleted records."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["only_deleted"]}," takes precedence if both are supplied."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deleted records may carry an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_erased"]}," flag. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_erased"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," the"," ","record's private fields have been permanently removed under a data-erasure"," ","request, and those fields will be empty or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},". An erased record cannot be"," ","restored to its original state — treat it as a tombstone, not as recoverable"," ","data."]}]},"headings":[{"value":"Filtering, sorting and pagination","id":"filtering-sorting-and-pagination","depth":1},{"value":"Pagination","id":"pagination","depth":2},{"value":"Sorting","id":"sorting","depth":2},{"value":"Filtering","id":"filtering","depth":2},{"value":"Expanding related data","id":"expanding-related-data","depth":2},{"value":"Localisation","id":"localisation","depth":2},{"value":"Soft-deleted records","id":"soft-deleted-records","depth":2}],"frontmatter":{"seo":{"title":"Filtering, sorting and pagination"}},"lastModified":"2026-08-18T06:10:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api-docs/guides/request-filters","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}