> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.iot.telia.lt/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.iot.telia.lt/_mcp/server. > Learn how to implement paging, filtering, and sorting for large datasets in API collection GET requests with query parameters and response headers. API supports paging, filtering, sorting on big lists (GET operation on collection resources). Paging, filtering, and sorting are handled as query parameters in requests, while meta data describing the response are returned as header parameters. > **Info** > > Only the collection GET requests that handle large datasets implement this feature. ## Paging Paging accepts query parameters that specify: * `per_page` - maximum number of resources to be retrieved within a single response (page size) * If `per_page` is \< 1 the default page size is used * `per_page` is set to a predefined maximum value if it's too big * `page` - number of returned chunk within the complete set (`page#`). * If the requested page doesn't exist the first (for page \< 1) or the last page (for page > `last_page`) is returned The response header contains: * `Link` - URLs for navigational links used to retrieve first, previous, next and last page in a dataset * `X-Count-Per-Page` - Requested `per_page` parameter * `X-Current-Page` - Current page number within the set * `X-Total-Count` - Total element count in the dataset * `X-Total-Pages` - Total pages count in the dataset ### Example Request ```bash curl -v -H "Authorization: Bearer AUTH_TOKEN" "https://iot.telia.lt/api/v1/endpoint?page=3&per_page=100" ``` Response header ```http Link: ;rel="first", ;rel="prev", ;rel="next", ;rel="last" X-Count-Per-Page: 100 X-Current-Page: 3 X-Total-Count: 5000 X-Total-Pages: 50 ``` > **Info** > > Link header should contain any (optional) filter, sort, and expansion query parameters. ## Filtering Filtering criteria is included in the request URL as `q` query parameter which accepts a comma-separated list of `field:criteria` pairs. The following example demonstrates a `GET` request to `/api/v1/endpoint`. The `q` parameter then has the following query parameters: * `status` = `0` * `name` = `arduino` To form this request, the following pattern would be required: `/api/v1/endpoint?q=status:0,name:arduino` A valid curl for a query of this type would look like the following: ```bash # Filter arduino endpoints with status "Enabled" curl -v -H "Authorization: Bearer AUTH_TOKEN" "https://iot.telia.lt/api/v1/endpoint?q=status:0,name:arduino" ``` When using query parameters, the following match patterns apply to queries: | Entrypoint | Field | Match pattern | | :------------------------------------------------------- | :-------------- | :------------------------------------------------------------------------ | | `/api/v1/endpoint` | `id` | exact match | | | `name` | wildcard | | | `tags` | wildcard | | | `ipAddress` | `startsWith` | | | `imei` | `startsWith` | | | `iccid` | exact match if size of search string is bigger than 19, else `startsWith` | | `/api/v1/sim` | `id` | exact match | | | `imsi` | exact match if size of search string is bigger than 14, else `startsWith` | | | `msisdns` | `startsWith` | | | `iccid` | exact match if size of search string is bigger than 19, else `startsWith` | | `/api/v1/organisation` | `id` | exact match | | | `name` | wildcard | | | `ext_reference` | wildcard | | | `created` | wildcard | | `/api/v1/user` | `username` | wildcard | | | `name` | wildcard | | `/api/v1/tariff_plan` | `notes` | wildcard | | | `name` | wildcard | | | `description` | wildcard | | `/api/v1/{endpoint, sim, organisation, user}/{id}/event` | `id` | exact match | | **OR** `/api/v1/event` **(only with new stack)** | `tags` | term query | | | `description` | query string query | | | `severity` | exact match | | | `endpoint` | term query | | | `ip_address` | valid IPv4/v6 address | | | `imei` | exact match | | | `iccid` | exact match | | | `imsi` | exact match | | | `source` | exact match | | | `type` | exact match | | | `from` | `date range` | | | `until` | date range | | | `organisation` | term query | | | `alert` | exact match | | | `user` | term query | If filtering is applied the header contains: * `X-Filter` - filter criteria ## Sorting Sorting criteria is included in the request URL as \{sort} parameter as a comma separated list of sorting properties. The default sort order is ascending. Descending order is specified with `-` (dash). ```bash # Sort endpoints by name (descending) and status curl -v -H "Authorization: Bearer AUTH_TOKEN" "https://iot.telia.lt/api/v1/endpoint?sort=-name,status" ``` If sorting is applied the header contains: * `X-Sort` - sort criteria