v1 (beta)

How pagination works on the Rated API v1.

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 and here for Polygon.

See details on the parameters below 👇

Paramters	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
        }
    ]
}