Pagination in the Instana REST API

Edit online

Pagination is used in the Instana REST API to efficiently navigate through significant volumes of data returned from Instana's API endpoints. This guide explains how pagination works and how you can use it effectively.

Understanding pagination

Edit online

When an API endpoint returns a list of resources that is extensive, the API uses pagination to separate the results into chunks of a more manageable size. The parameters of pagination control which subset of data is returned in each API response. Page-based and cursor-based are the two types of pagination used in Instana.

Page-based pagination

Edit online

In page-based pagination, the page (sometimes referred to as limit or offset) and pageSize parameters are commonly used to control the subset of data that is returned in each API request.

Data model

Edit online

Instana's page-based pagination type Pagination has the following data model:

{
    "type": "object",
    "properties": {
        "page": {
            "type": "integer",
            "format": "int32",
            "minimum": 1
        },
        "pageSize": {
            "type": "integer",
            "format": "int32",
            "maximum": 200,
            "minimum": 1
        }
    }
}

Attribute table

Edit online

The following table outlines the definitions for the attributes of the Pagination type:

Attribute Description
page The specific page within the dataset where results that are returned appear.
pageSize The size of each page or chunk of data that is returned.

Example of pagination

Edit online

The following example shows the usage of Pagination:

{
    "page": 2,
    "pageSize": 50
}

Cursor-based pagination

Edit online

In cursor-based pagination, a cursor points to a position in the dataset from which data is retrieved. Instana has two subtypes of cursor-based pagination: a general purpose cursor pagination (CursorPagination) and a cursor pagination specific to Infrastructure Monitoring (CursorPaginationInfraExploreCursor).

General purpose cursor pagination

Edit online

The CursorPagination type is the most common form of cursor-based pagination in Instana's API landscape.

Data model

Edit online

Instana's general-purpose, cursor-based pagination type, CursorPagination, has the following data model:

{
    "type": "object",
    "properties": {
        "ingestionTime": {
            "type": "integer",
            "format": "int64"
        },
        "offset": {
            "type": "integer",
            "format": "int32"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "maximum": 200,
            "minimum": 1
        }
    }
}

Attribute table

Edit online

The following table outlines the definitions for the attributes of the CursorPagination type:

Attribute Description
ingestionTime A pointer to a starting point to use between successive queries.
offset A pointer to a starting point to use between successive queries.
retrievalSize The number of values to retrieve.

Example of cursor-based pagination

Edit online

The following example shows the usage of CursorPagination:

{
    "ingestionTime": 1720104883,
    "offset": 2,
    "retrievalSize": 45
}

Cursor pagination for Infrastructure Monitoring

Edit online

This pagination type is named CursorPaginationInfraExploreCursor and has both a cursor and a retrievalSize. CursorPaginationInfraExploreCursor used only in the Infrastructure Analyze group of endpoints.

Data model

Edit online

The cursor-based pagination type CursorPaginationInfraExploreCursor that is used in Infrastructure Analyze has the following data model:

{
    "type": "object",
    "properties": {
        "cursor": {
            "$ref": "#/components/schemas/InfraExploreCursor"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "description": "number of values to return"
        }
    }
}

The InfraExplorerCursor property of cursor-based pagination is itself an object and has the following data model:

{
    "type": "object",
    "description": "cursor to use between successive queries"
}

Attribute table

Edit online

The following table outlines the definitions for the attributes of the CursorPaginationInfraExploreCursor type:

Attribute Description
cursor A pointer to a starting point to use between successive queries.
retrievalSize The number of values to retrieve. 
{
    "type": "object",
    "properties": {
        "cursor": {
            "$ref": "#/components/schemas/InfraExploreCursor"
        },
        "retrievalSize": {
            "type": "integer",
            "format": "int32",
            "description": "number of values to return"
        }
    }
}