Pagination in the Instana REST API

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

Understanding pagination

When an API endpoint returns a list of resources that is large, 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

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

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

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

Table 1. Attribute of pagination
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

The following example shows the usage of Pagination:

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

Where can it be used?

The following groups of API endpoints use the Pagination schema:

The Application Resources that are set of API endpoints also offers page-based pagination. Application resources do not use the Pagination schema, but instead includes a page and a pageSize attribute in the request payload schema.

Cursor-based pagination

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

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

Data model

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

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

Table 2. Attribute of cursor pagination
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

The following example shows the usage of CursorPagination:

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

Where can it be used?

The following groups of API endpoints use the CursorPagination schema:

Cursor pagination for Infrastructure Monitoring

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

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

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

Table 3. Attribute of cursor pagination of infra explorer cursor
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"
        }
    }
}

Where can it be used?

The following groups of API endpoints use the CursorPaginationInfraExploreCursor schema:

Infrastructure Analyze

For more information on API usage and best practices, see API documentation.