Pagination

All top-level API resources have support for bulk fetches through API methods that respond with a list. These list API methods share a common structure and accept, at a minimum, the following two parameters: limit and offset.

Pagination limits and page size

Rated API v1 uses offset based pagination through the limit and offset parameters. Both parameters accept an existing object ID value (see below) and return objects in chronological order. The limit parameter specifies how many records to fetch per page. The offset parameter indicates where to start fetching data or how many records to skip, defining the initial position within the list. See details on the parameters below:

Parameters	Description
`limit`	Limit specifies how many records to fetch per page. Default value is 10.
`offset`	Offset indicates where to start fetching data or how many records to skip, defining the initial position within the list. Default value is 0.

In the response, you will get the total number of pages which signifies how many pages of data we have for the requested information. For example, if you call https://api.rated.network/v1/eth/entities/Lido/effectiveness?entityType=pool&sortOrder=desc you will get about 120 pages of data which signifies about 1,200 days worth of data.

Example of a paginated response

{
    "previous": null,
    "next": "http://api.rated.network/v1/eth/entities/Lido/effectiveness?entityType=pool&sortOrder=desc&limit=2&offset=2",
    "pages": 119,
    "results": [
        {
            "hour": null,
            "day": 1216,
            "startDay": null,
            "endDay": null,
            "startEpoch": 273600,
            "endEpoch": 273824,
            "startDate": null,
            "endDate": null,
            "date": "2024-03-31",
            "validatorCount": 297904,
            "avgInclusionDelay": 1.038763630790519,
            "avgUptime": 0.9992577027051225,
            "avgCorrectness": 0.9876840011118172,
            "avgProposerEffectiveness": 99.36076243607621,
            "avgValidatorEffectiveness": 95.17034897418644,
            "avgAttesterEffectiveness": 95.1591781211266
        },
        {
            "hour": null,
            "day": 1215,
            "startDay": null,
            "endDay": null,
            "startEpoch": 273375,
            "endEpoch": 273599,
            "startDate": null,
            "endDate": null,
            "date": "2024-03-30",
            "validatorCount": 298294,
            "avgInclusionDelay": 1.0294108088847345,
            "avgUptime": 0.9993213691520342,
            "avgCorrectness": 0.9880952559065563,
            "avgProposerEffectiveness": 99.65690759377856,
            "avgValidatorEffectiveness": 96.04556135704149,
            "avgAttesterEffectiveness": 96.0357475833673
        }
    ]
}

Depending on the request, you can also get more than one page of results. You can navigate between these pages using the previous and next URLs. Just use the URL in next to continue fetching the rest of the data. You will also get a url in previous as you navigate throught pages 2,3,4… and so on. When there’s no more data left, the Rated API will stop giving you the link and show next: null.

Sorting and Filters

We have also introduced the ability to sort the response based on the day or date. You can use the sorting parameters sortBy and sortOrder to retrieve the response in chronological or reverse chronological order. See details on the parameters below:

Parameters	Description
`sortBy`	sortBy specifies what parameter you’d like to order your response by. Default value is `day` for Ethereum.
`sortOrder`	sortOrder indicates how the sorting will be order. Can be `desc` or `asc` and defaults to `asc`.

Additionally, you can filter what date range you wish to get your response for using the fromDate and toDate or fromDay and toDay query parameters. To see how time works, head here for Ethereum. See details on the parameters below:

Parameters	Description
`fromDate`	The inclusive start date for the query in the format `YYYY-MM-DD`. Cannot be after `toDate`.
`toDate`	The inclusive end date for the query in the format `YYYY-MM-DD`. Cannot be before `fromDate`.
`fromDay`	The inclusive start day for the query. Cannot be after `toDay`.
`toDay`	The inclusive end day for the query. Cannot be before `fromDay`.

Depending on the endpoint and time window aggregations you set using granularity, the response will contain a list of items with startDate, endDate, fromDay and EndDay that collectively correspond to the filter you applied over a particular granularity. See details on the parameters below:

Parameters	Description
`startDate`	The inclusive start date for the item in a list in the format `YYYY-MM-DD`.
`endDate`	The inclusive end date for the item in a list in the format `YYYY-MM-DD`.
`startDay`	The inclusive start day for the item in a list.
`endDay`	The inclusive end day for the item in a list.

For example, if you call

https://api.rated.network/v1/eth/entities/Lido/effectiveness?fromDate=2024-03-01&toDate=2024-03-31&granularity=week&entityType=pool&limit=2

you will get a paginated list of two items per page, with weekly aggregates of effectiveness for Lido (pool) from 1st March 2024 to 31st March 2024 with weekly start date/day and end date/day.

Example of a filtered response

{
    "previous": null,
    "next": "http://api.rated.network/v1/eth/entities/Lido/effectiveness?fromDate=2024-03-01&toDate=2024-03-31&granularity=week&entityType=pool&limit=2&offset=2",
    "pages": 3,
    "results": [
        {
            "hour": null,
            "day": 1186,
            "startDay": 1186,
            "endDay": 1188,
            "startEpoch": 266850,
            "endEpoch": 267524,
            "startDate": "2024-03-01",
            "endDate": "2024-03-03",
            "date": null,
            "validatorCount": 307230,
            "avgInclusionDelay": 1.0148401909467175,
            "avgUptime": 0.9991621137562569,
            "avgCorrectness": 0.9942351947995315,
            "avgProposerEffectiveness": 99.73424219448532,
            "avgValidatorEffectiveness": 97.9455545121116,
            "avgAttesterEffectiveness": 97.94053939240182
        },
        {
            "hour": null,
            "day": 1189,
            "startDay": 1189,
            "endDay": 1195,
            "startEpoch": 267525,
            "endEpoch": 269099,
            "startDate": "2024-03-04",
            "endDate": "2024-03-10",
            "date": null,
            "validatorCount": 307299,
            "avgInclusionDelay": 1.018166812052602,
            "avgUptime": 0.9990804092593188,
            "avgCorrectness": 0.9940622570239258,
            "avgProposerEffectiveness": 99.70565569238833,
            "avgValidatorEffectiveness": 97.6359636193607,
            "avgAttesterEffectiveness": 97.6302452977211
        }
    ]
}

Getting started

Rated API

Endpoints

Glossary

Guides

Tools

Sorting and Filters

​Pagination limits and page size

​Sorting and Filters

Pagination limits and page size

Sorting and Filters