Pagination in Axiom API

Pagination allows you to retrieve responses in manageable chunks.

You can use pagination for the following endpoints:

• Run Query
• Run Query (Legacy)

​

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 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.
• 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.
• Specify startTime and endTime in the body of your API request.

​

Response format

​

Page through the result set

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

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

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)

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

{
  "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.

Example request to go to next page for Run Query:

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):

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"
  }'