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 might be large, the API uses pagination to split the results into chunks of a more manageable size. Pagination parameters control, which subset of data is returned in each API response. Two types of pagination are used in Instana: page-based and cursor-base.

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 definitions for the attributes in the Pagination type are as follows:

Attribute Description
page The specific page within the dataset that is the starting point for the results that get returned.
pageSize The size of each page or chunk of data that is returned.

Example

An example looks like:

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

Where can it be used?

The following groups of API endpoints use the Pagination schema:

The Application Resources set of API endpoints also offers page-based pagination. It does 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 definitions for the attributes in the CursorPagination type are as follows:

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

An example looks like:

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

Where can it be used?

The following groups of API endpoints use the CursorPagination schema:

Cursor Pagination specific to Infrastructure Monitoring

This pagination type is named CursorPaginationInfraExploreCursor and has both a cursor and a retrievalSize. It is 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"
        }
    }
}

Its InfraExplorerCursor property is itself an object and has the following data model:

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

Attribute table

The definitions for the attributes in the CursorPaginationInfraExploreCursor type are as follows:

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:

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

This page provides an overview of the pagination for using the Instana REST API, helping you to manage the retrieval of API data more efficiently.