Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revoke support for pagination #167

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Revoke support for pagination #167

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db62742
Revoke support for pagination
tothmano Dec 4, 2024
fe4147a
Update pagination.mdx
tothmano Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 3 additions & 138 deletions restapi/pagination.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,146 +1,11 @@
---
title: 'Pagination in Axiom API'
description: 'Learn how to use pagination with the Axiom API.'
title: 'Pagination with Axiom API'
description: 'This page will explain how to use pagination with the Axiom API.'
sidebarTitle: Pagination
tags:
['axiom documentation', 'documentation', 'axiom', 'axiom api', 'rest api', 'rest', 'pagination', 'cursor', 'query']
---

Pagination allows you to retrieve responses in manageable chunks.

You can use pagination for the following endpoints:
- [Run Query](/restapi/endpoints/queryApl)
- [Run Query (Legacy)](/restapi/endpoints/queryDataset)

## Pagination mechanism

Axiom uses cursor-based pagination for these endpoints. The parameters and mechanisms differ between the current and legacy endpoints.

### Run Query

To use pagination with the Run Query endpoint:
- Include the [`limit` operator](/apl/tabular-operators/limit-operator) in the APL query of your API request. The argument of this operator determines the number of events to display per page.
- Use `sort by _time asc` or `sort by _time desc` in the APL query. This returns the results in ascending or descending chronological order. For more information, see [sort operator](/apl/tabular-operators/sort-operator).
- Specify `startTime` and `endTime` in the body of your API request.

### Run Query (Legacy)

To use pagination with the legacy Run Query endpoint:
- Add the `limit` parameter to the body of your API request. The value of this parameter determines the number of events to display per page.
- Add the `order` parameter to the body of your API request. In the value of this parameter, order the results by time in either ascending or descending chronological order. For example, `[{ "field": "_time", "desc": true }]`. For more information, see [order operator](/apl/tabular-operators/order-operator).
- Specify `startTime` and `endTime` in the body of your API request.

## Response format

<ResponseField name="status" type="object">
Contains metadata about the response including pagination information.
</ResponseField>

<ResponseField name="status.minCursor" type="string">
Cursor for the first item in the current page.
</ResponseField>

<ResponseField name="status.maxCursor" type="string">
Cursor for the last item in the current page.
</ResponseField>

<ResponseField name="status.rowsMatched" type="integer">
Total number of rows matching the query.
</ResponseField>

<ResponseField name="matches" type="array">
Contains the list of returned objects.
</ResponseField>

## Page through the result set

To page through the result set, add the `cursor` parameter to the body of your API request.

<ParamField query="cursor" type="string">
Optional. A cursor for use in pagination. Use the cursor string returned in previous responses to fetch the next or previous page of results.
</ParamField>

The `minCursor` and `maxCursor` fields in the response are boundaries that help you page through the result set.

For queries with descending order (`_time DESC`), use `minCursor` from the response as the `cursor` in your next request to go to the next page. You reach the end when your provided `cursor` matches the `minCursor` in the response.

For queries with ascending order (`_time ASC`), use `maxCursor` from the response as the `cursor` in your next request to go to the next page. You reach the end when your provided `cursor` matches the `maxCursor` in the response.

If the query returns fewer results than the specified limit, paging can stop.

## Examples

### Example request Run Query

```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/_apl?format=tabular' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"apl": "dataset | sort by _time desc | limit 100",
"startTime": "2024-01-01T00:00:00.000Z",
"endTime": "2024-01-31T23:59:59.999Z"
}'
```

### Example request Run Query (Legacy)

```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/{dataset_id}/query' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"startTime": "2024-01-01T00:00:00.000Z",
"endTime": "2024-01-31T23:59:59.999Z",
"limit": 100,
"order": [{ "field": "_time", "desc": true }]
}'
```

### Example response

```json
{
"status": {
"rowsMatched": 2500,
"minCursor": "0d3wo7v7e1oii-075a8c41710018b9-0000ecc5",
"maxCursor": "0d3wo7v7e1oii-075a8c41710018b9-0000faa3"
},
"matches": [
// ... events ...
]
}
```

### Example request to page through the result set

To page through the result set, use the appropriate cursor value in your next request. For more information, see [Page through the result set](#page-through-the-result-set).

Example request to go to next page for Run Query:

```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/_apl' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"apl": "dataset | sort by _time desc | limit 100",
"startTime": "2024-01-01T00:00:00.000Z",
"endTime": "2024-01-31T23:59:59.999Z",
"cursor": "0d3wo7v7e1oii-075a8c41710018b9-0000ecc5"
}'
```

Example request to go to next page for Run Query (Legacy):

```bash
curl -X 'POST' 'https://api.axiom.co/v1/datasets/{dataset_id}/query' \
-H 'Authorization: Bearer API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"startTime": "2024-01-01T00:00:00.000Z",
"endTime": "2024-01-31T23:59:59.999Z",
"limit": 100,
"order": [{ "field": "_time", "desc": true }],
"cursor": "0d3wo7v7e1oii-075a8c41710018b9-0000ecc5"
}'
```
Currently, the Axiom API doesn’t support the pagination of responses. Support for pagination is coming in early 2025. To express interest in the feature, [contact Axiom](https://axiom.co/contact).